1 2 Copyright (C) 2002-2010 Karl J. Runge <runge (a] karlrunge.com> 3 All rights reserved. 4 5 x11vnc README file Date: Mon Dec 27 20:58:57 EST 2010 6 7 The following information is taken from these URLs: 8 9 http://www.karlrunge.com/x11vnc/index.html 10 http://www.karlrunge.com/x11vnc/x11vnc_opts.html 11 ... 12 13 they contain the most up to date info. 14 15 16 ======================================================================= 17 http://www.karlrunge.com/x11vnc/index.html: 18 19 20 _________________________________________________________________ 21 22 x11vnc: a VNC server for real X displays 23 (to FAQ) (to Downloads) (to Building) (to Beta Test) 24 (to Donations) [PayPal] 25 26 x11vnc allows one to view remotely and interact with real X displays 27 (i.e. a display corresponding to a physical monitor, keyboard, and 28 mouse) with any VNC viewer. In this way it plays the role for Unix/X11 29 that WinVNC plays for Windows. 30 31 It has built-in SSL/TLS encryption and 2048 bit RSA authentication, 32 including VeNCrypt support; UNIX account and password login support; 33 server-side scaling; single port HTTPS/HTTP+VNC; Zeroconf service 34 advertising; and TightVNC and UltraVNC file-transfer. It has also been 35 extended to work with non-X devices: natively on Mac OS X Aqua/Quartz, 36 webcams and TV tuner capture devices, and embedded Linux systems such 37 as Qtopia Core. Full IPv6 support is provided. More features are 38 described here. 39 40 It also provides an encrypted Terminal Services mode (-create, -svc, 41 or -xdmsvc options) based on Unix usernames and Unix passwords where 42 the user does not need to memorize his VNC display/port number. 43 Normally a virtual X session (Xvfb) is created for each user, but it 44 also works with X sessions on physical hardware. See the tsvnc 45 terminal services mode of the SSVNC viewer for one way to take 46 advantage of this mode. 47 48 I wrote x11vnc back in 2002 because x0rfbserver was basically 49 impossible to build on Solaris and had poor performance. The primary 50 x0rfbserver build problems centered around esoteric C++ toolkits. 51 x11vnc is written in plain C and needs only standard libraries and so 52 should work on nearly all Unixes, even very old ones. I also created 53 enhancements to improve the interactive response, added many features, 54 and etc. 55 56 This page including the FAQ contains much information [*]; solutions 57 to many problems; and interesting applications, but nevertheless 58 please feel free to contact me if you have problems or questions (and 59 if I save you time or expense by giving you some of my time, please 60 consider a PayPal Donation.) Do check the FAQ and this page first; I 61 realize the pages are massive, but you can often use your browser's 62 find-in-page search action using a keyword to find the answer to your 63 problem or question. 64 65 SSVNC: An x11vnc side-project provides an Enhanced TightVNC Viewer 66 package (SSVNC) for Unix, Windows, and Mac OS X with automatic SSL 67 and/or SSH tunnelling support, SSL Certificate creation, Saved 68 connection profiles, Zeroconf, VeNCrypt, and built-in Proxy support. 69 Added features for the TightVNC Unix viewer: NewFBSize, ZRLE encoding, 70 Viewer-side Scaling, cursor alphablending, low color modes, and 71 enhanced popup menu; UltraVNC extensions support for: File Transfer, 72 Text Chat, Single Window, Server Input, and 1/n Scaling extensions, 73 and UltraVNC DSM encryption. The SSVNC bundle could be placed on, say, 74 a USB memory stick for SSL/SSH VNC viewing from nearly any networked 75 computer. 76 77 _________________________________________________________________ 78 79 Announcements: 80 81 Important: If you created any permanent SSL certificates (e.g. via 82 "x11vnc -ssl SAVE ...") on a Debian or Ubuntu system from Sept. 2006 83 through May 2008, then those keys are likely extremely weak and can be 84 easily cracked. The certificate files should be deleted and recreated 85 on a non-Debian system or an updated one. See 86 http://www.debian.org/security/2008/dsa-1571 for details. The same 87 applies to SSH keys (not used by x11vnc directly, but many people use 88 SSH tunnels for VNC access.) 89 90 FAQ moved: The huge FAQ has finally been moved to its own page. If you 91 are trying to follow someone's link to an FAQ once on this page it is 92 now a broken link. Try inserting the string "faq.html", e.g.: 93 from: http://www.karlrunge.com/x11vnc/#faq-singleclick 94 to: http://www.karlrunge.com/x11vnc/faq.html#faq-singleclick 95 96 Apologies for the inconvenience, unfortunately it is not possible to 97 automatically redirect to the new page since the '#' anchor is not 98 sent to the webserver. 99 100 _________________________________________________________________ 101 102 Background: 103 104 VNC (Virtual Network Computing) is a very useful network graphics 105 protocol (applications running on one computer but displaying their 106 windows on another) in the spirit of X, however, unlike X, the 107 viewing-end is very simple and maintains no state. It is a remote 108 framebuffer (RFB) protocol. 109 110 Some VNC links: 111 * http://www.realvnc.com 112 * http://www.tightvnc.com 113 * http://www.ultravnc.com/ 114 * http://www.testplant.com/products/vine_server/OS_X 115 116 For Unix, the traditional VNC implementation includes a "virtual" X11 117 server Xvnc (usually launched via the vncserver command) that is not 118 associated with a physical display, but provides a "fake" one X11 119 clients (xterm, firefox, etc.) can attach to. A remote user then 120 connects to Xvnc via the VNC client vncviewer from anywhere on the 121 network to view and interact with the whole virtual X11 desktop. 122 123 The VNC protocol is in most cases better suited for remote connections 124 with low bandwidth and high latency than is the X11 protocol because 125 it involves far fewer "roundtrips" (an exception is the cached pixmap 126 data on the viewing-end provided by X.) Also, with no state maintained 127 the viewing-end can crash, be rebooted, or relocated and the 128 applications and desktop continue running. Not so with X11. 129 130 So the standard Xvnc/vncserver program is very useful, I use it for 131 things like: 132 * Desktop conferencing with other users (e.g. code reviews.) 133 * Long running apps/tasks I want to be able to view from many places 134 (e.g. from home and work.) 135 * Motif, GNOME, and similar applications that would yield very poor 136 performance over a high latency link. 137 138 However, sometimes one wants to connect to a real X11 display (i.e. 139 one attached to a physical monitor, keyboard, and mouse: a Workstation 140 or a SunRay session) from far away. Maybe you want to close down an 141 application cleanly rather than using kill, or want to work a bit in 142 an already running application, or would like to help a distant 143 colleague solve a problem with their desktop, or would just like to 144 work out on the deck for a while. This is where x11vnc is useful. 145 _________________________________________________________________ 146 147 How to use x11vnc: 148 149 In this basic example let's assume the remote machine with the X 150 display you wish to view is "far-away.east:0" and the workstation you 151 are presently working at is "sitting-here.west". 152 153 Step 0. Download x11vnc (see below) and have it available to run on 154 far-away.east (on some linux distros it is as easy as "apt-get install 155 x11vnc", "emerge x11vnc", etc.) Similarly, have a VNC viewer (e.g. 156 vncviewer) ready to run on sitting-here.west. We recommend TightVNC 157 Viewers (see also our SSVNC viewer.) 158 159 Step 1. By some means log in to far-away.east and get a command shell 160 running there. You can use ssh, or even rlogin, telnet, or any other 161 method to do this. We do this because the x11vnc process needs to be 162 run on the same machine the X server process is running on (otherwise 163 things would be extremely slow.) 164 165 Step 2. In that far-away.east shell (with command prompt "far-away>" 166 in this example) run x11vnc directed at the far-away.east X session 167 display: 168 169 far-away> x11vnc -display :0 170 171 You could have also set the environment variable DISPLAY=:0 instead of 172 using "-display :0". This step attaches x11vnc to the far-away.east:0 173 X display (i.e. no viewer clients yet.) 174 175 Common Gotcha: To get X11 permissions right, you may also need to set 176 the XAUTHORITY environment variable (or use the -auth option) to point 177 to the correct MIT-MAGIC-COOKIE file (e.g. /home/joe/.Xauthority.) If 178 x11vnc does not have the authority to connect to the display it exits 179 immediately. More on how to fix this below. 180 181 If you suspect an X11 permissions problem do this simple test: while 182 sitting at the physical X display open a terminal window 183 (gnome-terminal, xterm, etc.) You should be able to run x11vnc 184 successfully in that terminal without any need for command line 185 options. If that works OK then you know X11 permissions are the only 186 thing preventing it from working when you try to start x11vnc via a 187 remote shell. Then fix this with the tips below. 188 189 Note as of Feb/2007 you can also try the -find option instead of 190 "-display ..." and see if that finds your display and Xauthority. Note 191 as of Dec/2009 the -findauth and "-auth guess" options may be helpful 192 as well. 193 (End of Common Gotcha) 194 195 When x11vnc starts up there will then be much chatter printed out (use 196 "-q" to quiet it), until it finally says something like: 197 . 198 . 199 13/05/2004 14:59:54 Autoprobing selected port 5900 200 13/05/2004 14:59:54 screen setup finished. 201 13/05/2004 14:59:54 202 13/05/2004 14:59:54 The VNC desktop is far-away:0 203 PORT=5900 204 205 which means all is OK, and we are ready for the final step. 206 207 Step 3. At the place where you are sitting (sitting-here.west in this 208 example) you now want to run a VNC viewer program. There are VNC 209 viewers for Unix, Windows, MacOS, Java-enabled web browsers, and even 210 for PDA's like the Palm Pilot and Cell Phones! You can use any of them 211 to connect to x11vnc (see the above VNC links under "Background:" on 212 how to obtain a viewer for your platform or see this FAQ. For Solaris, 213 vncviewer is available in the Companion CD package SFWvnc.) 214 215 In this example we'll use the Unix vncviewer program on sitting-here 216 by typing the following command in a second terminal window: 217 218 sitting-here> vncviewer far-away.east:0 219 220 That should pop up a viewer window on sitting-here.west showing and 221 allowing interaction with the far-away.east:0 X11 desktop. Pretty 222 nifty! When finished, exit the viewer: the remote x11vnc process will 223 shutdown automatically (or you can use the -forever option to have it 224 wait for additional viewer connections.) 225 226 Common Gotcha: Nowadays there will likely be a host-level firewall on 227 the x11vnc side that is blocking remote access to the VNC port (e.g. 228 5900.) You will either have to open up that port (or a range of ports) 229 in your firewall administration tool, or try the SSH tunnelling method 230 below (even still the firewall must allow in the SSH port, 22.) 231 232 233 Shortcut: Of course if you left x11vnc running on far-away.east:0 in a 234 terminal window with the -forever option or as a service, you'd only 235 have to do Step 3 as you moved around. Be sure to use a VNC Password 236 or other measures if you do that. 237 238 239 Super Shortcut: Here is a potentially very easy way to get all of it 240 working. 241 * Have x11vnc (0.9.3 or later) available to run on the remote host 242 (i.e. in $PATH.) 243 * Download and unpack a SSVNC bundle (1.0.19 or later, e.g. 244 ssvnc_no_windows-1.0.28.tar.gz) on the Viewer-side machine. 245 * Start the SSVNC Terminal Services mode GUI: ./ssvnc/bin/tsvnc 246 * Enter your remote username@hostname (e.g. fred (a] far-away.east) in 247 the "VNC Terminal Server" entry. 248 * Click "Connect". 249 250 That will do an SSH to username@hostname and start up x11vnc and then 251 connect a VNC Viewer through the SSH encrypted tunnel. 252 253 There are a number of things assumed here, first that you are able to 254 SSH into the remote host; i.e. that you have a Unix account there and 255 the SSH server is running. On Unix and MacOS X it is assumed that the 256 ssh client command is available on the local machine (on Windows a 257 plink binary is included in the SSVNC bundle.) Finally, it is assumed 258 that you are already logged into an X session on the remote machine, 259 e.g. your workstation (otherwise, a virtual X server, e.g. Xvfb, will 260 be started for you.) 261 262 In some cases the remote SSH server will not run commands with the 263 same $PATH that you normally have in your shell there. In this case 264 click on Options -> Advanced -> X11VNC Options, and type in the 265 location of the x11vnc binary under "Full Path". (End of Super 266 Shortcut) 267 268 269 Desktop Sharing: The above more or less assumed nobody was sitting at 270 the workstation display "far-away.east:0". This is often the case: a 271 user wants to access her workstation remotely. Another usage pattern 272 has the user sitting at "far-away.east:0" and invites one or more 273 other people to view and interact with his desktop. Perhaps the user 274 gives a demo or presentation this way (using the telephone for vocal 275 communication.) A "Remote Help Desk" mode would be similar: a 276 technician connects remotely to the user's desktop to interactively 277 solve a problem the user is having. 278 279 For these cases it should be obvious how it is done. The above steps 280 will work, but more easily the user sitting at far-away.east:0 simply 281 starts up x11vnc from a terminal window, after which the guests would 282 start their VNC viewers. For this usage mode the "-connect 283 host1,host2" option may be of use to automatically connect to the 284 vncviewers in "-listen" mode on the list of hosts. 285 _________________________________________________________________ 286 287 Tunnelling x11vnc via SSH: 288 289 The above example had no security or privacy at all. When logging into 290 remote machines (certainly when going over the internet) it is best to 291 use ssh, or use a VPN (for a VPN, Virtual Private Network, the above 292 example should be pretty safe.) 293 294 For x11vnc one can tunnel the VNC protocol through an encrypted ssh 295 channel. It would look something like running the following commands: 296 sitting-here> ssh -t -L 5900:localhost:5900 far-away.east 'x11vnc -localhost 297 -display :0' 298 299 (you will likely have to provide passwords/passphrases to login from 300 sitting-here into your far-away.east Unix account; we assume you have 301 a login account on far-away.east and it is running the SSH server) 302 303 And then in another terminal window on sitting-here run the command: 304 sitting-here> vncviewer -encodings "copyrect tight zrle hextile" localhost:0 305 306 Note: The -encodings option is very important: vncviewer will often 307 default to "raw" encoding if it thinks the connection is to the local 308 machine, and so vncviewer gets tricked this way by the ssh 309 redirection. "raw" encoding will be extremely slow over a networked 310 link, so you need to force the issue with -encodings "copyrect tight 311 ...". Nowadays, not all viewers use the -encodings option, try 312 "-PreferredEncoding=ZRLE" (although the newer viewers seem to 313 autodetect well when to use raw or not.) 314 315 Note that "x11vnc -localhost ..." limits incoming vncviewer 316 connections to only those from the same machine. This is very natural 317 for ssh tunnelling (the redirection appears to come from the same 318 machine.) Use of a VNC password is also strongly recommended. 319 320 Note also the -t we used above (force allocate pseudoterminal), it 321 actually seems to improve interactive typing response via VNC! 322 323 You may want to add the -C option to ssh to enable compression. The 324 VNC compression is not perfect, and so this may help a bit. However, 325 over a fast LAN you probably don't want to enable SSH compression 326 because it can slow things down. Try both and see which is faster. 327 328 If your username is different on the remote machine use something 329 like: "fred (a] far-away.east" in the above ssh command line. 330 331 Some VNC viewers will do the ssh tunnelling for you automatically, the 332 TightVNC Unix vncviewer does this when the "-via far-away.east" option 333 is supplied to it (this requires x11vnc to be already running on 334 far-away.east or having it started by inetd(8).) See the 3rd script 335 example below for more info. 336 337 SSVNC: You may also want to look at the Enhanced TightVNC Viewer 338 (ssvnc) bundles because they contain scripts and GUIs to automatically 339 set up SSH tunnels (e.g. the GUI, "ssvnc", does it automatically and 340 so does this command: "ssvnc_cmd -ssh user (a] far-away.east:0") and can 341 even start up x11vnc as well. 342 343 The Terminal Services mode of SSVNC is perhaps the easiest way to use 344 x11vnc. You just need to have x11vnc available in $PATH on the remote 345 side (and can SSH to the host), and then on the viewer-side you type 346 something like: 347 tsvnc fred (a] far-away.east 348 349 everything else is done automatically for you. Normally this will 350 start a virtual Terminal Services X session (RAM-only), but if you 351 already have a real X session up on the physical hardware it will find 352 that one for you. 353 354 Gateways: If the machine you SSH into is not the same machine with 355 the X display you wish to view (e.g. your company provides incoming 356 SSH access to a gateway machine), then you need to change the above 357 to, e.g.: "-L 5900:OtherHost:5900": 358 sitting-here> ssh -t -L 5900:OtherHost:5900 gateway.east 359 360 Where gateway.east is the internet hostname (or IP) of the gateway 361 machine (SSH server.) 'OtherHost' might be, e.g., freds-pc or 362 192.168.2.33 (it is OK for these to be private hostnames or private IP 363 addresses, the host in -L is relative to the remote server side.) 364 365 Once logged in, you'll need to do a second login (ssh, rsh, etc.) to 366 the workstation machine 'OtherHost' and then start up x11vnc on it (if 367 it isn't already running.) (The "-connect gateway:59xx" option may be 368 another alternative here with the viewer already in -listen mode.) For 369 an automatic way to use a gateway and have all the network traffic 370 encrypted (including inside the firewall) see Chaining SSH's. 371 372 These gateway access modes also can be done automatically for you via 373 the "Proxy/Gateway" setting in SSVNC (including the Chaining SSH's 374 case, "Double Proxy".) 375 376 Firewalls/Routers: 377 378 A lot of people have inexpensive devices for home or office that act 379 as a Firewall and Router to the machines inside on a private LAN. One 380 can usually configure the Firewall/Router from inside the LAN via a 381 web browser. 382 383 Often having a Firewall/Router sitting between the vncviewer and 384 x11vnc will make it impossible for the viewer to connect to x11vnc. 385 386 One thing that can be done is to redirect a port on the 387 Firewall/Router to, say, the SSH port (22) on an inside machine (how 388 to do this depends on your particular Firewall/Router, often the 389 router config URL is http://192.168.100.1 See www.portforward.com for 390 more info.) This way you reach these computers from anywhere on the 391 Internet and use x11vnc to view X sessions running on them. 392 393 Suppose you configured the Firewall/Router to redirect these ports to 394 two internal machines: 395 Port 12300 -> 192.168.1.3, Port 22 (SSH) 396 Port 12301 -> 192.168.1.4, Port 22 (SSH) 397 398 (where 192.168.1.3 is "jills-pc" and 192.168.1.4 is "freds-pc".) Then 399 the ssh's would look something like: 400 sitting-here> ssh -t -p 12300 -L 5900:localhost:5900 jill (a] far-away.east 'x11v 401 nc -localhost -display :0' 402 sitting-here> ssh -t -p 12301 -L 5900:localhost:5900 fred (a] far-away.east 'x11v 403 nc -localhost -display :0' 404 405 Where far-away.east means the hostname (or IP) that the 406 Router/Firewall is using (for home setups this is usually the IP 407 gotten from your ISP via DHCP, the site http://www.whatismyip.com/ is 408 a convenient way to determine what it is.) 409 410 It is a good idea to add some obscurity to accessing your system via 411 SSH by using some high random port (e.g. 12300 in the above example.) 412 If you can't remember it, or are otherwise not worried about port 413 scanners detecting the presence of your SSH server and there is just 414 one internal PC involved you could map 22: 415 Port 22 -> 192.168.1.3, Port 22 (SSH) 416 417 Again, this SSH gateway access can be done automatically for you via 418 the "Proxy/Gateway" setting in SSVNC. And under the "Remote SSH 419 Command" setting you can enter the x11vnc -localhost -display :0. 420 421 Host-Level-Firewalls: even with the hardware Firewall/Router problem 422 solved via a port redirection, most PC systems have their own Host 423 level "firewalls" enabled to protect users from themselves. I.e. the 424 system itself blocks all incoming connections. So you will need to see 425 what is needed to configure it to allow in the port (e.g. 22) that you 426 desire. E.g. Yast, Firestarter, iptables(1), etc.. 427 428 VNC Ports and Firewalls: The above discussion was for configuring the 429 Firewall/Router to let in port 22 (SSH), but the same thing can be 430 done for the default VNC port 5900: 431 Port 5900 -> 192.168.1.3, Port 5900 (VNC) 432 Port 5901 -> 192.168.1.4, Port 5900 (VNC) 433 434 (where 192.168.1.3 is "jills-pc" and 192.168.1.4 is "freds-pc".) This 435 could be used for normal, unencrypted connections and also for SSL 436 encrypted ones. 437 438 The VNC displays to enter in the VNC viewer would be, say, 439 "far-away.east:0" to reach jills-pc and "far-away.east:1" to reach 440 freds-pc. We assume above that x11vnc is using port 5900 (and any 441 Host-Level-firewalls on jills-pc has been configured to let that port 442 in.) Use the "-rfbport" option to tell which port x11vnc should listen 443 on. 444 445 For a home system one likely does not have a hostname and would have 446 to use the IP address, say, "24.56.78.93:0". E.g.: 447 vncviewer 24.56.78.93:0 448 449 You may want to choose a more obscure port on the router side, e.g. 450 5944, to avoid a lot of port scans finding your VNC server. For 5944 451 you would tell the viewer to use: 452 vncviewer 24.56.78.93:44 453 454 The IP address would need to be communicated to the person running the 455 VNC Viewer. The site http://www.whatismyip.com/ can help here. 456 457 _________________________________________________________________ 458 459 Scripts to automate ssh tunneling: As discussed below, there may be 460 some problems with port 5900 being available. If that happens, the 461 above port and display numbers may change a bit (e.g. -> 5901 and :1). 462 However, if you "know" port 5900 will be free on the local and remote 463 machines, you can easily automate the above two steps by using the 464 x11vnc option -bg (forks into background after connection to the 465 display is set up) or using the -f option of ssh. Some example scripts 466 are shown below. Feel free to try the ssh -C to enable its compression 467 and see if that speeds things up noticeably. 468 _________________________________________________________________ 469 470 #1. A simple example script, assuming no problems with port 5900 being 471 taken on the local or remote sides, looks like: 472 #!/bin/sh 473 # usage: x11vnc_ssh <host>:<xdisplay> 474 # e.g.: x11vnc_ssh snoopy.peanuts.com:0 475 # (user@host:N also works) 476 477 host=`echo $1 | awk -F: '{print $1}'` 478 disp=`echo $1 | awk -F: '{print $2}'` 479 if [ "x$disp" = "x" ]; then disp=0; fi 480 481 cmd="x11vnc -display :$disp -localhost -rfbauth .vnc/passwd" 482 enc="copyrect tight zrle hextile zlib corre rre raw" 483 484 ssh -f -t -L 5900:localhost:5900 $host "$cmd" 485 486 for i in 1 2 3 487 do 488 sleep 2 489 if vncviewer -encodings "$enc" :0; then break; fi 490 done 491 492 See also rx11vnc.pl below. 493 _________________________________________________________________ 494 495 #2. Another method is to start the VNC viewer in listen mode 496 "vncviewer -listen" and have x11vnc initiate a reverse connection 497 using the -connect option: 498 #!/bin/sh 499 # usage: x11vnc_ssh <host>:<xdisplay> 500 # e.g.: x11vnc_ssh snoopy.peanuts.com:0 501 # (user@host:N also works) 502 503 host=`echo $1 | awk -F: '{print $1}'` 504 disp=`echo $1 | awk -F: '{print $2}'` 505 if [ "x$disp" = "x" ]; then disp=0; fi 506 507 cmd="x11vnc -display :$disp -localhost -connect localhost" # <== note new opt 508 ion 509 enc="copyrect tight zrle hextile zlib corre rre raw" 510 511 vncviewer -encodings "$enc" -listen & 512 pid=$! 513 ssh -t -R 5500:localhost:5500 $host "$cmd" 514 kill $pid 515 516 Note the use of the ssh option "-R" instead of "-L" to set up a remote 517 port redirection. 518 _________________________________________________________________ 519 520 #3. A third way is specific to the TightVNC vncviewer special option 521 -via for gateways. The only tricky part is we need to start up x11vnc 522 and give it some time (5 seconds in this example) to start listening 523 for connections (so we cannot use the TightVNC default setting for 524 VNC_VIA_CMD): 525 #!/bin/sh 526 # usage: x11vnc_ssh <host>:<xdisplay> 527 # e.g.: x11vnc_ssh snoopy.peanuts.com:0 528 529 host=`echo $1 | awk -F: '{print $1}'` 530 disp=`echo $1 | awk -F: '{print $2}'` 531 if [ "x$disp" = "x" ]; then disp=0; fi 532 533 VNC_VIA_CMD="ssh -f -t -L %L:%H:%R %G x11vnc -localhost -rfbport 5900 -display 534 :$disp; sleep 5" 535 export VNC_VIA_CMD 536 537 vncviewer -via $host localhost:0 # must be TightVNC vncviewer. 538 539 Of course if you already have the x11vnc running waiting for 540 connections (or have it started out of inetd(8)), you can simply use 541 the TightVNC "vncviewer -via gateway host:port" in its default mode to 542 provide secure ssh tunnelling. 543 _________________________________________________________________ 544 545 546 547 VNC password file: Also note in the #1. example script that the option 548 "-rfbauth .vnc/passwd" provides additional protection by requiring a 549 VNC password for every VNC viewer that connects. The vncpasswd or 550 storepasswd programs, or the x11vnc -storepasswd option can be used to 551 create the password file. x11vnc also has the slightly less secure 552 -passwdfile and "-passwd XXXXX" options to specify passwords. 553 554 Very Important: It is up to YOU to tell x11vnc to use password 555 protection (-rfbauth or -passwdfile), it will NOT do it for you 556 automatically or force you to (use -usepw if you want to be forced 557 to.) The same goes for encrypting the channel between the viewer and 558 x11vnc: it is up to you to use ssh, stunnel, -ssl mode, a VPN, etc. 559 (use the Enhanced TightVNC Viewer (SSVNC) GUI if you want to be forced 560 to use SSL or SSH.) For additional safety, also look into the -allow 561 and -localhost options and building x11vnc with tcp_wrappers support 562 to limit host access. 563 564 _________________________________________________________________ 565 566 Tunnelling x11vnc via SSL/TLS: 567 568 One can also encrypt the VNC traffic using an SSL/TLS tunnel such as 569 stunnel.mirt.net (also stunnel.org) or using the built-in (Mar/2006) 570 -ssl openssl mode. A SSL-enabled Java applet VNC Viewer is also 571 provided in the x11vnc package (and https can be used to download it.) 572 573 Although not as ubiquitous as ssh, SSL tunnelling still provides a 574 useful alternative. See this FAQ on -ssl and -stunnel modes for 575 details and examples. 576 577 The Enhanced TightVNC Viewer (SSVNC) bundles contain some convenient 578 utilities to automatically set up an SSL tunnel from the viewer-side 579 (i.e. to connect to "x11vnc -ssl ...".) And many other enhancements 580 too. 581 _________________________________________________________________ 582 583 Downloading x11vnc: 584 585 x11vnc is a contributed program to the LibVNCServer project at 586 SourceForge.net. I use libvncserver for all of the VNC aspects; I 587 couldn't have done without it. The full source code may be found and 588 downloaded (either file-release tarball or GIT tree) from the above 589 link. As of Sep 2010, the x11vnc-0.9.12.tar.gz source package is 590 released (recommended download). The x11vnc 0.9.12 release notes. 591 592 The x11vnc package is the subset of the libvncserver package needed to 593 build the x11vnc program. Also, you can get a copy of my latest, 594 bleeding edge x11vnc-0.9.13-dev.tar.gz tarball to build the most up to 595 date one. 596 597 Precompiled Binaries/Packages: See the FAQ below for information 598 about where you might obtain a precompiled x11vnc binary from 3rd 599 parties and some ones I create. 600 601 VNC Viewers: To obtain VNC viewers for the viewing side (Windows, Mac 602 OS, or Unix) try these links: 603 * http://www.tightvnc.com/download.html 604 * http://www.realvnc.com/download-free.html 605 * http://sourceforge.net/projects/cotvnc/ 606 * http://www.ultravnc.com/ 607 * Our Enhanced TightVNC Viewer (SSVNC) 608 609 [ssvnc.gif] 610 611 612 More tools: Here is a ssh/rsh wrapper script rx11vnc that attempts to 613 automatically do the above Steps 1-3 for you (provided you have 614 ssh/rsh login permission on the machine x11vnc is to be run on.) The 615 above example would be: "rx11vnc far-away.east:0" typed into a shell 616 on sitting-here.west. Also included is an experimental script 617 rx11vnc.pl that attempts to tunnel the vnc traffic through an ssh port 618 redirection (and does not assume port 5900 is free.) Have a look at 619 them to see what they do and customize as needed: 620 * rx11vnc wrapper script 621 * rx11vnc.pl wrapper script to tunnel traffic thru ssh 622 623 _________________________________________________________________ 624 625 Building x11vnc: 626 627 Make sure you have all the needed build/compile/development packages 628 installed (e.g. Linux distributions foolishly don't install them by 629 default.) See this build FAQ for more details. 630 631 If your OS has libjpeg.so and libz.so in standard locations you can 632 build as follows (example given for the 0.9.12 release of x11vnc: 633 replace with the version you downloaded): 634 (un-tar the x11vnc+libvncserver tarball) 635 # gzip -dc x11vnc-0.9.12.tar.gz | tar -xvf - 636 637 (cd to the source directory) 638 # cd x11vnc-0.9.12 639 640 (run configure and then run make) 641 # ./configure 642 # make 643 644 (if all went OK, copy x11vnc to the desired destination, e.g. $HOME/bin) 645 # cp ./x11vnc/x11vnc $HOME/bin 646 647 Or do make install, it will probably install to /usr/local/bin (run 648 ./configure --help for information on customizing your configuration, 649 e.g. --prefix=/my/place.) You can now run it via typing "x11vnc", 650 "x11vnc -help | more", "x11vnc -forever -shared -display :0", etc. 651 652 653 Note: Currently gcc is recommended to build libvncserver. In some 654 cases it will build with non-gcc compilers, but the resulting binary 655 sometimes fails to run properly. For Solaris pre-built gcc binaries 656 are at http://www.sunfreeware.com/. Some Solaris pre-built x11vnc 657 binaries are here. 658 659 However, one user reports it does work fine when built with Sun Studio 660 10, so YMMV. In fact, here is a little build script to do this on 661 Solaris 10: 662 #!/bin/sh 663 PATH=/usr/ccs/bin:/opt/SUNWspro/bin:$PATH; export PATH 664 665 CC='cc' \ 666 CFLAGS='-xO4' \ 667 LDFLAGS='-L/usr/sfw/lib -L/usr/X11/lib -R/usr/sfw/lib -R/usr/X11/lib' \ 668 CPPFLAGS='-I /usr/sfw/include -I/usr/X11/include' \ 669 ./configure 670 671 MAKE="make -e" 672 AM_CFLAGS="" 673 export MAKE AM_CFLAGS 674 $MAKE 675 676 In general you can use the "make -e" trick if you don't like 677 libvncserver's choice of AM_CFLAGS. See the build scripts below for 678 more ideas. Scripts similar to the above have been shown to work with 679 vendor C compilers on HP-UX (ccom: HP92453-01) and Tru64 (Compaq C 680 V6.5-011.) 681 682 You can find information on Misc. Build problems here. 683 684 _________________________________________________________________ 685 686 Building on Solaris, FreeBSD, etc: Depending on your version of 687 Solaris or other Unix OS the jpeg and/or zlib libraries may be in 688 non-standard places (e.g. /usr/local, /usr/sfw, /opt/sfw, etc.) 689 690 Note: If configure cannot find these two libraries then TightVNC and 691 ZRLE encoding support will be disabled, and you don't want that!!! The 692 TightVNC encoding gives very good compression and performance, it even 693 makes a noticeable difference over a fast LAN. 694 695 696 Shortcuts: On Solaris 10 you can pick up almost everything just by 697 insuring that your PATH has /usr/sfw/bin (for gcc) and /usr/ccs/bin 698 (for other build tools), e.g.: 699 env PATH=/usr/sfw/bin:/usr/ccs/bin:$PATH sh -c './configure; make' 700 701 (The only thing this misses is /usr/X11/lib/libXrandr.so.2, which is 702 for the little used -xrandr option, see the script below to pick it up 703 as well.) 704 705 706 libjpeg is included in Solaris 9 and later (/usr/sfw/include and 707 /usr/sfw/lib), and zlib in Solaris 8 and later (/usr/include and 708 /usr/lib.) So on Solaris 9 you can pick up everything with something 709 like this: 710 env PATH=/usr/local/bin:/usr/ccs/bin:$PATH sh -c './configure --with-jpeg=/us 711 r/sfw; make' 712 713 assuming your gcc is in /usr/local/bin and x11vnc 0.7.1 or later. 714 These are getting pretty long, see those assignments split up in the 715 build script below. 716 717 718 If your system does not have these libraries at all you can get the 719 source for the libraries to build them: libjpeg is available at 720 ftp://ftp.uu.net/graphics/jpeg/ and zlib at http://www.gzip.org/zlib/. 721 See also http://www.sunfreeware.com/ for Solaris binary packages of 722 these libraries as well as for gcc. Normally they will install into 723 /usr/local but you can install them anywhere with the 724 --prefix=/path/to/anywhere, etc. 725 726 727 Here is a build script that indicates one way to pass the library 728 locations information to the libvncserver configuration via the 729 CPPFLAGS and LDFLAGS environment variables. 730 ---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8 731 <--- 732 #!/bin/sh 733 734 # Build script for Solaris, etc, with gcc, libjpeg and libz in 735 # non-standard locations. 736 737 # set to get your gcc, etc: 738 # 739 PATH=/path/to/gcc/bin:/usr/ccs/bin:/usr/sfw/bin:$PATH 740 741 JPEG=/path/to/jpeg # set to maybe "/usr/local", "/usr/sfw", or "/opt/sfw" 742 ZLIB=/path/to/zlib # set to maybe "/usr/local", "/usr/sfw", or "/opt/sfw" 743 744 # Below we assume headers in $JPEG/include and $ZLIB/include and the 745 # shared libraries are in $JPEG/lib and $ZLIB/lib. If your situation 746 # is different change the locations in the two lines below. 747 # 748 CPPFLAGS="-I $JPEG/include -I $ZLIB/include" 749 LDFLAGS="-L$JPEG/lib -R $JPEG/lib -L$ZLIB/lib -R $ZLIB/lib" 750 751 # These two lines may not be needed on more recent Solaris releases: 752 # 753 CPPFLAGS="$CPPFLAGS -I /usr/openwin/include" 754 LDFLAGS="$LDFLAGS -L/usr/openwin/lib -R /usr/openwin/lib" 755 756 # These are for libXrandr.so on Solaris 10: 757 # 758 CPPFLAGS="$CPPFLAGS -I /usr/X11/include" 759 LDFLAGS="$LDFLAGS -L/usr/X11/lib -R /usr/X11/lib" 760 761 # Everything needs to built with _REENTRANT for thread safe errno: 762 # 763 CPPFLAGS="$CPPFLAGS -D_REENTRANT" 764 765 export PATH CPPFLAGS LDFLAGS 766 767 ./configure 768 make 769 770 ls -l ./x11vnc/x11vnc 771 772 ---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8 773 <--- 774 775 Then do make install or copy the x11vnc binary to your desired 776 destination. 777 778 BTW, To run a shell script, just cut-and-paste the above into a file, 779 say "myscript", then modify the "/path/to/..." items to correspond to 780 your system/environment, and then type: "sh myscript" to run it. 781 782 Note that on Solaris make is /usr/ccs/bin/make, so that is why the 783 above puts /usr/ccs/bin in PATH. Other important build utilities are 784 there too: ld, ar, etc. Also, it is probably a bad idea to have 785 /usr/ucb in your PATH while building. 786 787 Starting with the 0.7.1 x11vnc release the "configure --with-jpeg=DIR 788 --with-zlib=DIR" options are handy if you want to avoid making a 789 script. 790 791 If you need to link OpenSSL libssl.a on Solaris see this method. 792 793 If you need to build on Solaris 2.5.1 or earlier or other older Unix 794 OS's, see this workaround FAQ. 795 796 797 Building on FreeBSD, OpenBSD, ...: The jpeg libraries seem to be in 798 /usr/local or /usr/pkg on these OS's. You won't need the openwin stuff 799 in the above script (but you may need /usr/X11R6/....) Also starting 800 with the 0.7.1 x11vnc release, this usually works: 801 ./configure --with-jpeg=/usr/local 802 make 803 804 805 Building on HP-UX: For jpeg and zlib you will need to do the same 806 sort of thing as described above for Solaris. You set CPPFLAGS and 807 LDFLAGS to find them (see below for an example.) You do not need to do 808 any of the above /usr/openwin stuff. Also, HP-UX does not seem to 809 support -R, so get rid of the -R items in LDFLAGS. Because of this, at 810 runtime you may need to set LD_LIBRARY_PATH or SHLIB_PATH to indicate 811 the directory paths so the libraries can be found. It is a good idea 812 to have static archives, e.g. libz.a and libjpeg.a for the nonstandard 813 libraries so that they get bolted into the x11vnc binary (and so won't 814 get "lost".) 815 816 Here is what we recently did to build x11vnc 0.7.2 on HP-UX 11.11 817 ./configure --with-jpeg=$HOME/hpux/jpeg --with-zlib=$HOME/hpux/zlib 818 make 819 820 Where we had static archives (libjpeg.a, libz.a) only and header files 821 in the $HOME/hpux/... directories as discussed for the build script. 822 823 On HP-UX 11.23 and 11.31 we have had problems compiling with gcc. 824 "/usr/include/rpc/auth.h:87: error: field 'syncaddr' has incomplete 825 type". As a workaround for x11vnc 0.9.4 and later set your CPPFLAGS to 826 include: 827 CPPFLAGS="-DIGNORE_GETSPNAM" 828 export CPPFLAGS 829 830 This disables a very rare usage mode for -unixpw_nis by not trying 831 getspnam(3). 832 833 Using HP-UX's C compiler on 11.23 and 11.31 we have some severe 834 compiler errors that have not been worked around yet. If you need to 835 do this, contact me and I will give you a drastic recipe that will 836 produce a working binary. 837 838 839 Building on AIX: AIX: one user had to add the "X11.adt" package to 840 AIX 4.3.3 and 5.2 to get build header files like XShm.h, etc. You may 841 also want to make sure that /usr/lpp/X11/include, etc is being picked 842 up by the configure and make. 843 844 For a recent build on AIX 5.3 we needed to add these CFLAGS to be able 845 to build with gcc: 846 env CFLAGS='-maix64 -Xlinker -bbigtoc' ./configure ... 847 848 we also built our own libjpeg and libz using -maix64. 849 850 BTW, one way to run an Xvfb-like virtual X server for testing on AIX 851 is something like "/usr/bin/X11/X -force -vfb -ac :1". 852 853 854 Building on Mac OS X: There is now native Mac OS X support for 855 x11vnc by using the raw framebuffer feature. This mode does not use or 856 need X11 at all. To build you may need to disable X11: 857 ./configure --without-x ... 858 make 859 860 However, if your system has the Mac OS X build package for X11 apps 861 you will not need to supply the "--without-x" option (in this case the 862 resulting x11vnc would be able to export both the native Mac OS X 863 display and windows displayed in the XDarwin X server.) Be sure to 864 include the ./configure option to find libjpeg on your system. 865 866 867 OpenSSL: Starting with version 0.8.3 x11vnc can now be built with 868 SSL/TLS support. For this to be enabled the libssl.so library needs to 869 be available at build time. So you may need to have additional 870 CPPFLAGS and LDFLAGS items if your libssl.so is in a non-standard 871 place. As of x11vnc 0.9.4 there is also the --with-ssl=DIR configure 872 option. 873 874 On Solaris using static archives libssl.a and libcrypto.a instead of 875 .so shared libraries (e.g. from www.sunfreeware.com), we found we 876 needed to also set LDFLAGS as follows to get the configure to work: 877 env LDFLAGS='-lsocket -ldl' ./configure --with-ssl=/path/to/openssl ... 878 make 879 880 _________________________________________________________________ 881 882 Beta Testing: 883 884 I don't have any formal beta-testers for the releases of x11vnc, so 885 I'd appreciate any additional testing very much. 886 887 Thanks to those who suggested features and helped beta test x11vnc 888 0.9.12 released in Sep 2010! 889 890 Please help test and debug the 0.9.13 version for release sometime in 891 Winter 2010. 892 893 The version 0.9.13 beta tarball is kept here: 894 x11vnc-0.9.13-dev.tar.gz 895 896 There are also some Linux, Solaris, Mac OS X, and other OS test 897 binaries here. Please kick the tires and report bugs, performance 898 regressions, undesired behavior, etc. to me. 899 900 To aid testing of the built-in SSL/TLS support for x11vnc, a number of 901 VNC Viewer packages for Unix, Mac OS X, and Windows have been created 902 that provide SSL Support for the TightVNC Viewer (this is done by 903 wrapper scripts and a GUI that starts STUNNEL.) It should be pretty 904 convenient for automatic SSL and SSH connections. It is described in 905 detail at and can be downloaded from the Enhanced TightVNC Viewer 906 (SSVNC) page. The SSVNC Unix viewer also supports x11vnc's symmetric 907 key encryption ciphers (see the 'UltraVNC DSM Encryption Plugin' 908 settings panel.) 909 910 911 Here are some features that will appear in the 0.9.13 release: 912 * Improved support for non-X11 touchscreen devices (e.g. handheld or 913 cell phone) via Linux uinput input injection. Additional tuning 914 parameters are added. TSLIB touchscreen calibration is supported. 915 Tested on Qtmoko Neo Freerunner. A tool, misc/uinput.pl, is 916 provided to diagnose uinput behavior on new devices. The env. 917 vars. X11VNC_UINPUT_BUS and X11VNC_UINPUT_VERSION are available if 918 leaving them unset does not work. 919 * The Linux uinput non-X11 input injection can now be bypassed: 920 events can be directly written to the /dev/input/event devices 921 specified by the user (direct_abs=..., etc.) A -pipeinput input 922 injection helper script, misc/qt_tslib_inject.pl is provided as a 923 tweakable non-builtin direct input injection method. 924 * The list of new uinput parameters for the above two features is: 925 pressure, tslib_cal, touch_always, dragskip, btn_touch; 926 direct_rel, direct_abs, direct_btn, direct_key. 927 * The MacOSX native server can now use OpenGL for the screen 928 capture. In nearly all cases this is faster than the raw 929 framebuffer capture method. There are build and run time flags, 930 X11VNC_MACOSX_NO_DEPRECATED, etc. to disable use of deprecated 931 input injection and screen access interfaces. Cursor shape now 932 works for 64bit binaries. 933 * The included SSL enabled Java VNC Viewers now handle Mouse Wheel 934 events. 935 * miscellaneous new features and changes: 936 * In -reflect mode, the libvncclient connection can now have the 937 pixel format modified via the environment variables 938 X11VNC_REFLECT_bitsPerSample, X11VNC_REFLECT_samplesPerPixel, and 939 X11VNC_REFLECT_bytesPerPixel 940 * In -create mode the following environment variables are added to 941 fine tune the behavior: FIND_DISPLAY_NO_LSOF: do not use lsof(1) 942 to try to determine the Linux VT, FIND_DISPLAY_NO_VT_FIND: do not 943 try to determine the Linux VT at all, X11VNC_CREATE_LC_ALL_C_OK: 944 do not bother undoing the setting LC_ALL=C that the create_display 945 script sets. The performance of the -create script has been 946 improved for large installations (100's of user sessions on one 947 machine.) 948 * In -unixpw mode, one can now Tab from login: to Password. 949 * An environment variable, X11VNC_SB_FACTOR, allows one to scale the 950 -sb screenblank sleep time from the default 2 secs. 951 * An experimental option -unixsock is available for testing. Note, 952 however, that it requires a manual change to 953 libvncserver/rfbserver.c for it to work. 954 * Documented that -grabkbd is no longer working with some/most 955 window managers (it can prevent resizing and menu posting.) 956 957 958 Here are some features that appeared in the 0.9.12 release (Sep/2010): 959 * One can now specify the maximum number of displays that can be 960 created in -create mode via the env. var. 961 X11VNC_CREATE_MAX_DISPLAYS 962 * The X11VNC_NO_LIMIT_SHM env. var. is added to skip any automatic 963 shared memory reduction. 964 * The kdm display manager is now detected when trying not to get 965 killed by the display manager. 966 * A compile time bug is fixed so that configuring using 967 --with-system-libvncserver pointing to LibVNCServer 0.9.7 works 968 again. A bug from forced use of Xdefs.h is worked around. 969 970 971 Here are some features that appeared in the 0.9.11 release (Aug/2010): 972 * The source tree is synchronized with the most recent libvncclient 973 (this only affects -reflect mode.) Build is fixed for 974 incompatibilities when using an external LibVNCServer (e.g. 975 ./configure --with-system-libvncserver...) Please help test these 976 build and runtime aspects and report back what you find, thanks. 977 * The SSL enabled Java VNC Viewer Makefile has been modified so that 978 the jar files that are built are compatible back to Java 1.4. 979 * In -create/-unixpw mode, the env. var. FD_USERPREFS may be set to 980 a filename in the user's home directory that includes default 981 username:options values (so the options do not need to be typed 982 every time at the login prompt.) 983 * In -reflect mode cursor position updates are now handled 984 correctly. 985 986 987 Here are some features that appeared in the 0.9.10 release (May/2010): 988 * The included SSL enabled Java applet viewer now supports Chained 989 SSL Certificates. The debugCerts=yes applet parameter aids 990 troubleshooting certificate validation. The x11vnc -ssl mode has 991 always supported chained SSL certificates (simply put the 992 intermediate certificates, in order, after the server certificate 993 in the pem file.) 994 * A demo CGI script desktop.cgi shows how to create an SSL 995 encrypted, multi-user x11vnc web login desktop service. The script 996 requires x11vnc version 0.9.10. The user logs into a secure web 997 site and gets his/her own virtual desktop (Xvfb.) x11vnc's SSL 998 enabled Java Viewer Applet is launched by the web browser for 999 secure viewing (and so no software needs to be installed on the 1000 viewer-side.) One can use the desktop.cgi script for ideas to 1001 create their own fancier or customized web login desktop service 1002 (e.g. user-creation, PHP, SQL, specialized desktop application, 1003 etc.) More info here. There is also an optional 'port redirection' 1004 mode that allows redirection to other SSL enabled VNC servers 1005 running inside the firewall. 1006 * Built-in support for IPv6 (128 bit internet addresses) is now 1007 provided. See the -6 and -connect options for details. 1008 Additionally, in case there are still problems with built-in IPv6 1009 support, a transitional tool is provided in inet6to4 that allows 1010 x11vnc (or any other IPv4 application) to receive connections over 1011 IPv6. 1012 * The Xdummy wrapper script for Xorg's dummy driver is updated and 1013 no longer requires being run as root. New service options are 1014 provided to select Xdummy over Xvfb as the virtual X server to be 1015 created. 1016 * The "%" unix password verification tricks for the -unixpw option 1017 are now documented. They have also been extended to run a command 1018 as the user if one sets the environment variable UNIXPW_CMD. The 1019 desktop.cgi demo script takes advantage of this new feature. 1020 * A bug has been fixed that would prevent the Java applet viewer 1021 from being downloaded successfully in single-port HTTPS/VNC inetd 1022 mode. The env. var. X11VNC_HTTPS_DOWNLOAD_WAIT_TIME can be used to 1023 adjust for how many seconds a -inetd or -https httpd download is 1024 waited for (default 15 seconds.) The applet will now autodetect 1025 x11vnc and use GET=1 for faster connecting. Many other 1026 improvements and fixes. 1027 * The TightVNC security type (TightVNC features enabler) now works 1028 for RFB version 3.8. 1029 * The X property X11VNC_TRAP_XRANDR can be set on a desktop to force 1030 x11vnc to use the -xrandr screen size change trapping code. 1031 * New remote control query options: pointer_x, pointer_y, 1032 pointer_same, pointer_root, and pointer_mask. A demo script using 1033 them misc/panner.pl is provided. 1034 * The -sslScripts option prints out the SSL certificate management 1035 scripts. 1036 1037 1038 Here are some features that appeared in the 0.9.9 release (Dec/2009): 1039 * The -unixpw_system_greeter option, when used in combined unixpw 1040 and XDMCP FINDCREATEDISPLAY mode (for example: -xdmsvc), enables 1041 the user to press Escape to jump directly to the XDM/GDM/KDM login 1042 greeter screen. This way the user avoids entering his unix 1043 password twice at X session creation time. Also, the unixpw login 1044 panel now has a short help displayed if the user presses 'F1'. 1045 * x11vnc now tries to be a little bit more aggressive in keeping up 1046 with VNC client's framebuffer update requests. Some broken VNC 1047 clients like Eggplant and JollysFastVNC continuously spray these 1048 requests at VNC servers (regardless of whether they have received 1049 any updates or not.) Under some circumstances this could lead to 1050 x11vnc falling behind. The -extra_fbur option allows one to fine 1051 tune the setting. Additionally, one may also dial down delays: 1052 e.g. "-defer 5" and "-wait 5" (or to 1 or even 0) or -nonap or 1053 -allinput to keep up with these VNC clients at the expense of 1054 increased system load. 1055 * Heuristics are applied to try to determine if the X display is 1056 currently in a Display Manager Greeter Login panel (e.g. GDM) If 1057 so, x11vnc's creation of any windows and use of XFIXES are 1058 delayed. This is to try to avoid x11vnc being killed after the 1059 user logs in if the GDM KillInitClients=true is in effect. So one 1060 does not need to set KillInitClients=false. Note that in recent 1061 GDM the KillInitClients option has been removed. Also delayed is 1062 the use of the XFIXES cursor fetching functionality; this avoids 1063 an Xorg bug that causes Xorg to crash right after the user logs 1064 in. 1065 * A new option -findauth runs the FINDDISPLAY script that applies 1066 heuristics that try to determine the XAUTHORITY file. The use of 1067 '-auth guess' will use the XAUTHORITY that -findauth reveals. This 1068 can be handy in with the lastest GDM where the ability to store 1069 cookies in ~/.Xauthority has been removed. If x11vnc is running as 1070 root (e.g. inetd) and you add -env FD_XDM=1 to the above -findauth 1071 or -auth guess command lines, it will find the correct XAUTHORITY 1072 for the given display (this works for XDM/GDM/KDM if the login 1073 greeter panel is up or if someone has already logged into an X 1074 session.) 1075 * The FINDDISPLAY and FINDCREATEDISPLAY modes (i.e. "-display 1076 WAIT:cmd=...", -find, -create) now work correctly for the 1077 user-supplied login program scheme "-unixpw_cmd ...", as long as 1078 the login program supports running commands specified in the 1079 environment variable "RFB_UNIXPW_CMD_RUN" as the logged-in user. 1080 The mode "-unixpw_nis ..." has also been made more consistent. 1081 * The -stunnel option (like -ssl but uses stunnel as an external 1082 helper program) now works with the -ssl "SAVE" and "TMP" special 1083 certificate names. The -sslverify and -sslCRL options now work 1084 correctly in -stunnel mode. Single port HTTPS connections are also 1085 supported for this mode. 1086 * There is an experimental Application Sharing mode that improves 1087 upon the -id/-sid single window sharing: -appshare (run "x11vnc 1088 -appshare -help" for more info.) It is still very primitive and 1089 approximate, but at least it displays multiple top-level windows. 1090 * The remote control command -R can be used to instruct x11vnc to 1091 resend its most recent copy of the Clipboard, Primary, or 1092 Cutbuffer selections: "x11vnc -R resend_clipboard", "x11vnc -R 1093 resend_primary", and "x11vnc -R resend_cutbuffer". 1094 * The fonts in the GUI (-gui) can now by set via environment 1095 variables, e.g. -env X11VNC_FONT_BOLD='Helvetica -16 bold' and 1096 -env X11VNC_FONT_FIXED='Courier -14'. 1097 * The XDAMAGE mechanism is now automatically disabled for a period 1098 of time if a game or screensaver generates too many XDAMAGE 1099 rectangles per second. This avoids the X11 event queue from 1100 soaking up too much memory. 1101 * There is an experimental workaround: "-env X11VNC_WATCH_DX_DY=1" 1102 that tries to avoid problems with poorly constructed menu themes 1103 that place the initial position of the mouse cursor inside a menu 1104 item's active zone. More information can be found here. 1105 1106 1107 Here are some features that appeared in the 0.9.8 release (Jul/2009): 1108 * Stability improvements to -threads mode. Running x11vnc this way 1109 is more reliable now. Threaded operation sometimes gives better 1110 interactive response and faster updates: try it out. The threaded 1111 mode now supports multiple VNC viewers using the same VNC 1112 encoding. The threaded mode can also yield a performance 1113 enhancement in the many client case (e.g. class-room broadcast.) 1114 We have tested with 30 to 50 simultaneous clients. See also 1115 -reflect. 1116 For simultaneous clients: the ZRLE encoding is thread safe on all 1117 platforms, and the Tight and Zlib encodings are currently only 1118 thread safe on Linux where thread local storage, __thread, is 1119 used. If your non-Linux system and compiler support __thread one 1120 can supply -DTLS=__thread to enable it. When there is only one 1121 connected client, all encodings are safe on all platforms. Note 1122 that some features (e.g. scroll detection and -ncache) may be 1123 disabled or run with reduced functionality in -threads mode. 1124 * Automatically tries to work around an Xorg server and GNOME bug 1125 involving infinitely repeating keys when turning off key 1126 repeating. Use -repeat if the automatic workaround fails. 1127 * Improved reliability of the Single Port SSL VNC and HTTPS java 1128 viewer applet delivery mechanism. 1129 * The -clip mode works under -rawfb. 1130 1131 1132 Here are some features that appeared in the 0.9.7 release (Mar/2009): 1133 * Support for polling Linux Virtual Terminals (also called virtual 1134 consoles) directly instead of using /dev/fb. The option to use is, 1135 for example, "-rawfb vt2" for Virtual Terminal 2, etc. In this 1136 case the special file /dev/vcsa2 is used to retrieve vt2's current 1137 text. Text and colors are shown, but no graphics. 1138 * Support for less than 8 bits per pixel framebuffers (e.g. 4 or 1 1139 bpp) in the -rawfb mode. 1140 * The SSL enabled UltraVNC Java viewer applet now has a [Home] entry 1141 in the "drives" drop down menu. This menu can be configured with 1142 the ftpDropDown applet parameter. All of the applet parameters are 1143 documented in classes/ssl/README. 1144 * Experimental support for VirtualGL's TurboVNC (an enhanced 1145 TightVNC for fast LAN high framerate usage.) 1146 * The CUPS Terminal Services helper mode has been improved. 1147 * Improvements to the -ncache_cr that allows smooth opaque window 1148 motions using the 'copyrect' encoding when using -ncache mode. 1149 * The -rmflag option enables a way to indicate to other processes 1150 x11vnc has exited. 1151 * Reverse connections using anonymous Diffie Hellman SSL encryption 1152 now work. 1153 1154 1155 Here are some features that appeared in the 0.9.6 release (Dec/2008): 1156 * Support for VeNCrypt SSL/TLS encrypted connections. It is enabled 1157 by default in the -ssl mode. VNC Viewers like vinagre, 1158 gvncviewer/gtk-vnc, the vencrypt package, SSVNC, and others 1159 support this encryption mode. It can also be used with the -unixpw 1160 option to enable Unix username and password authentication 1161 (VeNCrypt's "*Plain" modes.) A similar but older VNC security type 1162 "ANONTLS" (used by vino) is supported as well. See the -vencrypt 1163 and -anontls options for additional control. The difference 1164 between x11vnc's normal -ssl mode and VeNCrypt is that the former 1165 wraps the entire VNC connection in SSL (like HTTPS does for HTTP, 1166 i.e. "vncs://") while VeNCrypt switches on the SSL/TLS at a 1167 certain point during the VNC handshake. Use -sslonly to disable 1168 both VeNCrypt and ANONTLS (vino.) 1169 * The "-ssl ANON" option enables Anonymous Diffie-Hellman (ADH) key 1170 exchange for x11vnc's normal SSL/TLS operation. Note that 1171 Anonymous Diffie-Hellman uses encryption for privacy, but provides 1172 no authentication and so is susceptible to Man-In-The-Middle 1173 attacks (and so we do not recommend it: we prefer you use "-ssl 1174 SAVE", etc. and have the VNC viewer verify the cert.) The ANONTLS 1175 mode (vino) only supports ADH. VeNCrypt mode supports both ADH and 1176 regular X509 SSL certificates modes. For these ADH is enabled by 1177 default. See -vencrypt and -anontls for how to disable ADH. 1178 * For x11vnc's SSL/TLS modes, one can now specify a Certificate 1179 Revocation List (CRL) with the -sslCRL option. This will only be 1180 useful for wide deployments: say a company-wide x11vnc SSL access 1181 deployment using a central Certificate Authority (CA) via 1182 -sslGenCA and -sslGenCert. This way if a user has his laptop lost 1183 or stolen, you only have to revoke his key instead of creating a 1184 new Certificate Authority and redeploying new keys to all users. 1185 * The default SSL/TLS mode, "-ssl" (no pem file parameter supplied), 1186 is now the same as "-ssl SAVE" and will save the generated 1187 self-signed cert in "~/.vnc/certs/server.pem". Previously "-ssl" 1188 would create a temporary self-signed cert that was discarded when 1189 x11vnc exited. The reason for the change is to at least give the 1190 chance for the VNC Viewer side (e.g. SSVNC) to remember the cert 1191 to authenticate subsequent connections to the same x11vnc server. 1192 Use "-ssl TMP" to regain the previous behavior. Use "-ssl 1193 SAVE_NOPROMPT" to avoid being prompted about using passphrase when 1194 the certificate is created. 1195 * The option -http_oneport enables single-port HTTP connections via 1196 the Java VNC Viewer. So, for example, the web browser URL 1197 "http://myhost.org:5900" works the same as 1198 "http://myhost.org:5800", but with the convenience of only 1199 involving one port instead of two. This works for both unencrypted 1200 connections and for SSH tunnels (see -httpsredir if the tunnel 1201 port differs.) Note that HTTPS single-port operation in -ssl SSL 1202 encrypted mode has been available since x11vnc version 0.8.3. 1203 * For the -avahi/-zeroconf Service Advertizing mode, if x11vnc was 1204 not compiled with the avahi-client library, then an external 1205 helper program, either avahi-publish(1) (on Unix) or dns-sd(1) (on 1206 Mac OS X), is used instead. 1207 * The "-rfbport PROMPT" option will prompt the user via the GUI to 1208 select the VNC port (e.g. 5901) to listen on, and a few other 1209 basic settings. This enables a handy GUI mode for naive users: 1210 x11vnc -gui tray=setpass -rfbport PROMPT -logfile $HOME/.x11vnc.log.%VNCDISP 1211 LAY 1212 suitable for putting in a launcher or menu, e.g. x11vnc.desktop. 1213 The -logfile expansion is new too. In the GUI, the tray=setpass 1214 Properties panel has been improved. 1215 * The -solid solid background color option now works for the Mac OS 1216 X console. 1217 * The -reopen option instructs x11vnc to try to reopen the X display 1218 if it is prematurely closed by, say, the display manager (e.g. 1219 GDM.) 1220 1221 1222 Here are some features that appeared in the 0.9.5 release (Oct/2008): 1223 * Symmetric key encryption ciphers. ARC4, AES-128, AES-256, 1224 blowfish, and 3des are supported. Salt and initialization vector 1225 seeding is provided. These compliment the more widely used SSL and 1226 SSH encryption access methods. SSVNC also supports these 1227 encryption modes. 1228 * Scaling differently along the X- and Y-directions. E.g. "-scale 1229 1280x1024" or "-scale 0.8x0.75" Also, "-geometry WxH" is an 1230 alias for "-scale WxH" 1231 * By having SSVNC version 1.0.21 or later available in your $PATH, 1232 the -chatwindow option allows a UltraVNC Text Chat window to 1233 appear on the local X11 console/display (this way the remote 1234 viewer can chat with the person at the physical display; e.g. 1235 helpdesk mode.) This also works on the Mac OS X console if the 1236 Xquartz X11 server (enabled by default on leopard) is running for 1237 the chatwindow. 1238 * The HTTP Java viewer applet jar, classes/VncViewer.jar, has been 1239 updated with an improved implementation based on the code used by 1240 the classes/ssl applets. 1241 1242 1243 Here are some features that appeared in the 0.9.4 release (Sep/2008): 1244 * Improvements to the -find and -create X session finding or 1245 creating modes: new desktop types and service redirection options. 1246 Personal cupsd daemon and SSH port redirection helper for use with 1247 SSVNC's Terminal Services feature. 1248 * Reverse VNC connections via -connect work in the -find, -create 1249 and related -display WAIT:... modes. 1250 * Reverse VNC connections (either normal or SSL) can use a Web Proxy 1251 or a SOCKS proxy, or a SSH connection, or even a CGI URL to make 1252 the outgoing connection. See: -proxy. Forward connections can also 1253 use: -ssh. 1254 * Reverse VNC connections via the UltraVNC repeater proxy (either 1255 normal or SSL) are supported. Use either the "-connect 1256 repeater=ID:NNNN+host:port" or "-connect 1257 repeater://host:port+ID:NNNN" notation. The SSVNC VNC viewer also 1258 supports the UltraVNC repeater. Also, a perl repeater implemention 1259 is here: ultravnc_repeater.pl 1260 * Support for indexed colormaps (PseudoColor) with depths other than 1261 8 (from 1 to 16 now work) for non-standard hardware. Option 1262 "-advertise_truecolor" to handle some workaround in this mode. 1263 * Support for the ZYWRLE encoding, this is the RealVNC ZRLE encoding 1264 extended to do motion video and photo regions more efficiently by 1265 way of a Wavelet based transformation. 1266 * The -finddpy and -listdpy utilities help to debug and configure 1267 the -find, -create, and -display WAIT:... modes. 1268 * Some automatic detection of screen resizes are handled even if the 1269 -xrandr option is not supplied. 1270 * The -autoport options gives more control over the VNC port x11vnc 1271 chooses. 1272 * The -ping secs can be used to help keep idle connections alive. 1273 * Pasting of the selection/clipboard into remote applications (e.g. 1274 Java) has been improved. 1275 * Fixed a bug if a client disconnects during the 'speed-estimation' 1276 phase. 1277 * To unset Caps_Lock, Num_Lock and raise all keys in the X server 1278 use -clear_all. 1279 * Usage with dvorak keyboards has been improved. See also: -xkb. 1280 * The Java Viewer applet source code is now included in the 1281 x11vnc-0.9.*.tar.gz tarball. This means you can now build the Java 1282 viewer applet jar files from source. If you stopped shipping the 1283 Java viewer applet jar files due to lack of source code, you can 1284 start again. 1285 1286 1287 Here are some features that appeared in the 0.9.3 release (Oct/2007): 1288 * Viewer-side pixmap caching. A large area of pixels (at least 2-3 1289 times as big as the framebuffer itself; the bigger the better... 1290 default is 10X) is placed below the framebuffer to act as a 1291 buffer/cache area for pixel data. The VNC CopyRect encoding is 1292 used to move it around, so any viewer can take advantage of it. 1293 Until we start modifying viewers you will be able to see the cache 1294 area if you scroll down (this makes it easier to debug!) For 1295 testing the default is "-ncache 10". The unix Enhanced TightVNC 1296 Viewer ssvnc has a nice -ycrop option to help hide the pixel cache 1297 area from view. 1298 1299 1300 Here are some features that appeared in the 0.9.2 release (Jun/2007): 1301 * Building with no OpenSSL libssl available (or with --without-ssl) 1302 has been fixed. 1303 * One can configure x11vnc via "./configure 1304 --with-system-libvncserver" to use a system installed libvncserver 1305 library instead of the one bundled in the release tarball. 1306 * If UltraVNC file transfer or chat is detected, then VNC clients 1307 are "pinged" more often to prevent these side channels from 1308 becoming serviced too infrequently. 1309 * In -unixpw mode in the username and password dialog no text will 1310 be echoed if the first character sent is "Escape". This enables a 1311 convenience feature in SSVNC to send the username and password 1312 automatically. 1313 1314 1315 Here are some features that appeared in the 0.9.1 release (May/2007): 1316 * The UltraVNC Java viewer has been enhanced to support SSL (as the 1317 TightVNC viewer had been previously.) The UltraVNC Java supports 1318 ultravnc filetransfer, and so can be used as a VNC viewer on Unix 1319 that supports ultravnc filetransfer. It is in the 1320 classes/ssl/UltraViewerSSL.jar file (that is pointed to by 1321 ultra.vnc.) The signed applet SignedUltraViewerSSL.jar version 1322 (pointed to by ultrasigned.vnc) will be needed to access the local 1323 drive if you are using it for file transfer via a Web browser. 1324 Some other bugs in the UltraVNC Java viewer were fixed and a few 1325 improvements to the UI made. 1326 * A new Unix username login mode for VNC Viewers authenticated via a 1327 Client SSL Certificate: "-users sslpeer=". The emailAddress 1328 subject field is inspected for username@hostname and then acts as 1329 though "-users +username" has been supplied. This way the Unix 1330 username is identified by (i.e. simply extracted from) the Client 1331 SSL Certificate. This could be useful with -find, -create and -svc 1332 modes if you are also have set up and use VNC Client SSL 1333 Certificate authentication. 1334 * For external display finding/creating programs (e.g. WAIT:cmd=...) 1335 if the VNC Viewer is authenticated via a Client SSL Certificate, 1336 then that Certificate is available in the environment variable 1337 RFB_SSL_CLIENT_CERT. 1338 1339 1340 Here are some features that appeared in the 0.9 release (Apr/2007): 1341 * VNC Service advertising via mDNS / ZeroConf / BonJour with the 1342 Avahi client library. Enable via "-avahi" or "-zeroconf". 1343 * Implementations of UltraVNC's TextChat, SingleWindow, and 1344 ServerInput extensions (requires ultravnc viewer or ssvnc Unix 1345 viewer.) They toggle the selection of a single window (-id), and 1346 disable (friendly) user input and viewing (monitor blank) at the 1347 VNC server. 1348 * Short aliases "-find", "-create", "-svc", and "-xdmsvc" for 1349 commonly used FINDCREATEDISPLAY usage modes. 1350 * Reverse VNC connections (viewer listening) now work in SSL (-ssl) 1351 mode. 1352 * New options to control the Monitor power state and keyboard/mouse 1353 grabbing: -forcedpms, -clientdpms, -noserverdpms, and -grabalways. 1354 * A simple way to emulate inetd(8) to some degree via the "-loopbg" 1355 option. 1356 * Monitor the accuracy of XDAMAGE and apply "-noxdamage" if it is 1357 not working well. OpenGL applications like like beryl and MythTv 1358 have been shown to make XDAMAGE not work properly. 1359 * For Java SSL connections involving a router/firewall port 1360 redirection, an option -httpsredir to spare the user from needing 1361 to include &PORT=NNN in the browser URL. 1362 1363 1364 Here are some features that appeared in the 0.8.4 release (Feb/2007): 1365 * Native Mac OS X Aqua/Quartz support. (i.e. OSXvnc alternative; 1366 some activities are faster) 1367 * A new login mode: "-display WAIT:cmd=FINDCREATEDISPLAY -unixpw 1368 ..." that will Create a new X session (either virtual or real and 1369 with or without a display manager, e.g. kdm) for the user if it 1370 cannot find the user's X session display via the FINDDISPLAY 1371 method. See the -svc and the -xdmsvc aliases. 1372 * x11vnc can act as a VNC reflector/repeater using the "-reflect 1373 host:N" option. Instead of polling an X display, the remote VNC 1374 Server host:N is connected to and re-exported via VNC. This is 1375 intended for use in broadcasting a display to many (e.g. > 16; 1376 classroom or large demo) VNC viewers where bandwidth and other 1377 resources are conserved by spreading the load over a number of 1378 repeaters. 1379 * Wireframe copyrect detection for local user activity (e.g. someone 1380 sitting at the physical display moving windows) Use 1381 -nowireframelocal to disable. 1382 * The "-N" option couples the VNC Display number to the X Display 1383 number. E.g. if your X DISPLAY is :2 then the VNC display will be 1384 :2 (i.e. using port 5902.) If that port is taken x11vnc will exit. 1385 * Option -nodpms to avoid problems with programs like KDE's 1386 kdesktop_lock that keep restarting the screen saver every few 1387 seconds. 1388 * To automatically fix the common mouse motion problem on XINERAMA 1389 (multi-headed) displays, the -xwarppointer option is enabled by 1390 default when XINERAMA is active. 1391 1392 If you have a Mac please try out the native Mac OS X support, build 1393 with "./configure --without-x", or download a binary mentioned above, 1394 (even if you don't plan on ever using it in this mode!), and let me 1395 know how it went. Thanks. 1396 1397 1398 Here are some features that appeared in the 0.8.3 release (Nov/2006): 1399 * The -ssl option provides SSL encryption and authentication 1400 natively via the www.openssl.org library. One can use from a 1401 simple self-signed certificate server certificate up to full CA 1402 and client certificate authentication schemes. 1403 * Similar to -ssl, the -stunnel option starts up a SSL tunnel server 1404 stunnel (that must be installed separately on the system: 1405 stunnel.mirt.net ) to allow only encrypted SSL connections from 1406 the network. 1407 * The -sslverify option allows for authenticating VNC clients via 1408 their certificates in either -ssl or -stunnel modes. 1409 * Certificate creation and management tools are provide in the 1410 -sslGenCert, -sslGenCA, and related options. 1411 * An SSL enabled Java applet VNC Viewer applet is provided by x11vnc 1412 in classes/ssl/VncViewer.jar. In addition to normal HTTP, the 1413 applet may be loaded into the web browser via HTTPS (HTTP over 1414 SSL.) (one can use the VNC port, e.g. https://host:5900/, or also 1415 the separate -https port option.) A wrapper shell script 1416 ss_vncviewer is also provided that sets up a stunnel client-side 1417 tunnel on Unix systems. See Enhanced TightVNC Viewer (SSVNC) for 1418 other SSL/SSH viewer possibilities. 1419 * The -unixpw option supports Unix username and password 1420 authentication (a simpler variant is the -unixpw_nis option that 1421 works in environments where the encrypted passwords are readable, 1422 e.g. NIS.) The -ssl or -localhost + -stunnel options are enforced 1423 in this mode to prevent password sniffing. As a convenience, these 1424 requirements are lifted if a SSH tunnel can be deduced (but 1425 -localhost still applies.) 1426 * Coupling -unixpw with "-display WAIT:cmd=FINDDISPLAY" or "-display 1427 WAIT:cmd=FINDCREATEDISPLAY" provides a way to allow a user to 1428 login with their UNIX password and have their display connected to 1429 automatically. See the -svc and the -xdmsvc aliases. 1430 * Hooks are provided in the -unixpw_cmd and "-passwdfile 1431 cmd:,custom:..." options to allow you to supply your own 1432 authentication and password lookup programs. 1433 * x11vnc can be configured and built to not depend on X11 libraries 1434 "./configure --without-x" for -rawfb only operation (e.g. embedded 1435 linux console devices.) 1436 * The -rotate option enables you to rotate or reflect the screen 1437 before exporting via VNC. This is intended for use on handhelds 1438 and other devices where the rotation orientation is not "natural". 1439 * The "-ultrafilexfer" alias is provided and improved UltraVNC 1440 filetransfer rates have been achieved. 1441 * Under the "-connect_or_exit host" option x11vnc will exit 1442 immediately unless the reverse connection to host succeeds. The 1443 "-rfbport 0" option disables TCP listening for connections (useful 1444 for this mode.) 1445 * The "-rawfb rand" and "-rawfb none" options are useful for testing 1446 automation scripts, etc., without requiring a full desktop. 1447 * Reduced spewing of information at startup, use "-verbose" (also 1448 "-v") to turn it back on for debugging or if you are going to send 1449 me a problem report. 1450 1451 Here are some Previous Release Notes 1452 _________________________________________________________________ 1453 1454 Some Notes: 1455 1456 Both a client and a server: It is sometimes confusing to people that 1457 x11vnc is both a client and a server at the same time. It is an X 1458 client because it connects to the running X server to do the screen 1459 polls. Think of it as a rather efficient "screenshot" program running 1460 continuously. It is a server in the sense that it is a VNC server that 1461 VNC viewers on the network can connect to and view the screen 1462 framebuffer it manages. 1463 1464 When trying to debug problems, remember to think of both roles. E.g. 1465 "how is x11vnc connecting to the X server?", "how is the vncviewer 1466 connecting to x11vnc?", "what permits/restricts the connection?". Both 1467 links may have reachability, permission, and other issues. 1468 1469 Network performance: Whether you are using Xvnc or x11vnc it is 1470 always a good idea to have a solid background color instead of a 1471 pretty background image. Each and every re-exposure of the background 1472 must be resent over the network: better to have that background be a 1473 solid color that compresses very well compared to a photo image. (This 1474 is one place where the X protocol has an advantage over the VNC 1475 protocol.) I suggest using xsetroot, dtstyle or similar utility to set 1476 a solid background while using x11vnc. You can turn the pretty 1477 background image back on when you are using the display directly. 1478 Update: As of Feb/2005 x11vnc has the -solid [color] option that works 1479 on recent GNOME, KDE, and CDE and also on classic X (background image 1480 is on the root window.) Update: As of Oct/2007 x11vnc has the -ncache 1481 option that does a reasonable job caching the background (and other) 1482 pixmap data on the viewer side. 1483 1484 I also find the TightVNC encoding gives the best response for my usage 1485 (Unix <-> Unix over cable modem.) One needs a tightvnc-aware vncviewer 1486 to take advantage of this encoding. 1487 1488 TCP port issues: Notice the lines 1489 18/07/2003 14:36:31 Autoprobing selected port 5900 1490 PORT=5900 1491 1492 in the output. 5900 is the default VNC listening port (just like 6000 1493 is X11's default listening port.) Had port 5900 been taken by some 1494 other application, x11vnc would have next tried 5901. That would mean 1495 the viewer command above should be changed to vncviewer 1496 far-away.east:1. You can force the port with the "-rfbport NNNN" 1497 option where NNNN is the desired port number. If that port is already 1498 taken, x11vnc will exit immediately. The "-N" option will try to match 1499 the VNC display number to the X display. (also see the "SunRay 1500 Gotcha" note below) 1501 1502 Options: x11vnc has (far too) many features that may be activated 1503 via its command line options. Useful options are, e.g., -scale to do 1504 server-side scaling, and -rfbauth passwd-file to use VNC password 1505 protection (the vncpasswd or storepasswd programs, or the x11vnc 1506 -storepasswd option can be used to create the password file.) 1507 1508 Algorithm: How does x11vnc do it? Rather brute-forcedly: it 1509 continuously polls the X11 framebuffer for changes using 1510 XShmGetImage(). When changes are discovered, it instructs libvncserver 1511 which rectangular regions of the framebuffer have changed, and 1512 libvncserver compresses the changes and sends them off to any 1513 connected VNC viewers. A number of applications do similar things, 1514 such as x0rfbserver, krfb, x0vncserver, vino. x11vnc uses a 32 x 32 1515 pixel tile model (the desktop is decomposed into roughly 1000 such 1516 tiles), where changed tiles are found by pseudo-randomly polling 1 1517 pixel tall horizontal scanlines separated vertically by 32 pixels. 1518 This is a surprisingly effective algorithm for finding changed 1519 regions. For keyboard and mouse user input the XTEST extension is used 1520 to pass the input events to the X server. To detect XBell "beeps" the 1521 XKEYBOARD extension is used. If available, the XFIXES extension is 1522 used to retrieve the current mouse cursor shape. Also, if available 1523 the X DAMAGE extension is used to receive hints from the X server 1524 where modified regions on the screen are. This greatly reduces the 1525 system load when not much is changing on the screen and also improves 1526 how quickly the screen is updated. 1527 1528 Barbershop mirrors effect: What if x11vnc is started up, and 1529 vncviewer is then started up on the same machine and displayed on the 1530 same display x11vnc is polling? One might "accidentally" do this when 1531 first testing out the programs. You get an interesting 1532 recursive/feedback effect where vncviewer images keep popping up each 1533 one contained in the previous one and slightly shifted a bit by the 1534 window manager decorations. There will be an even more interesting 1535 effect if -scale is used. Also, if the XKEYBOARD is supported and the 1536 XBell "beeps" once, you get an infinite loop of beeps going off. 1537 Although all of this is mildly exciting it is not much use: you will 1538 normally run and display the viewer on a different machine! 1539 _________________________________________________________________ 1540 1541 Sun Ray Notes: 1542 1543 You can run x11vnc on your (connected or disconnected) SunRay session. 1544 Here are some notes on SunRay usage with x11vnc. 1545 1546 _________________________________________________________________ 1547 1548 Limitations: 1549 1550 * Due to the polling nature, some activities (opaque window moves, 1551 scrolling), can be pretty choppy/ragged and others (exposures of 1552 large areas) slow. Experiment with interacting a bit differently 1553 than you normally do to minimize the effects (e.g. do fullpage 1554 paging rather than line-by-line scrolling, and move windows in a 1555 single, quick motion.) Recent work has provided the 1556 -scrollcopyrect and -wireframe speedups using the CopyRect VNC 1557 encoding and other things, but they only speed up some activities, 1558 not all. 1559 * A rate limiting factor for x11vnc performance is that graphics 1560 hardware is optimized for writing, not reading (x11vnc reads the 1561 video framebuffer for the screen image data.) The difference can 1562 be a factor of 10 to 1000, and so it usually takes about 0.5-1 sec 1563 to read in the whole video hardware framebuffer (e.g. 5MB for 1564 1280x1024 at depth 24 with a read rate of 5-10MB/sec.) So whenever 1565 activity changes most of the screen (e.g. moving or iconifying a 1566 large window) there is a delay of 0.5-1 sec while x11vnc reads the 1567 changed regions in. 1568 A slow framebuffer read rate will often be the performance 1569 bottleneck on a fast LAN (whereas on slower links the reduced 1570 network bandwidth becomes the bottleneck.) 1571 Note: A quick way to get a 2X speedup of this for x11vnc is to 1572 switch your X server from depth 24 (32bpp) to depth 16 (16bpp.) 1573 You get a 4X speedup going to 8bpp, but the lack of color cells is 1574 usually unacceptable. 1575 To get a sense of the read and write speeds of your video card, 1576 you can run benchmarks like: "x11perf -getimage500", "x11perf 1577 -putimage500", "x11perf -shmput500" and for XFree86 displays with 1578 direct graphics access the "dga" command (press "b" to run the 1579 benchmark and then after a few seconds press "q" to quit.) Even 1580 this "dd if=/dev/fb0 of=/dev/null" often gives a good estimate. 1581 x11vnc also prints out its estimate: 1582 28/02/2009 11:11:07 Autoprobing TCP port 1583 28/02/2009 11:11:07 Autoprobing selected port 5900 1584 28/02/2009 11:11:08 fb read rate: 10 MB/sec 1585 28/02/2009 11:11:08 screen setup finished. 1586 We have seen a few cases where the hardware fb read speed is 1587 greater than 65 MB/sec: on high end graphics workstations from SGI 1588 and Sun, and also from a Linux user using nvidia proprietary 1589 drivers for his nvidia video card. Update 2008: thankfully, these 1590 sped up drivers are becoming more common on Linux and *BSD systems 1591 and that makes x11vnc run somewhat more quickly. Sometimes they 1592 have a read rate of over 400 MB/sec. 1593 On XFree86/Xorg it is actually possible to increase the 1594 framebuffer read speed considerably (10-100 times) by using the 1595 Shadow Framebuffer (a copy of the framebuffer is kept in main 1596 memory and this can be read much more quickly.) To do this one 1597 puts the line Option "ShadowFB" "true" in the Device section of 1598 the /etc/X11/XF86Config or /etc/X11/xorg.conf file. Note that this 1599 disables 2D acceleration at the physical display and so that might 1600 be unacceptable if one plays games, etc. on the machine's local 1601 display. Nevertheless this could be handy in some circumstances, 1602 e.g. if the slower speed while sitting at the physical display was 1603 acceptable (this seems to be true for most video cards these 1604 days.) Unfortunately it does not seem shadowfb can be turned on 1605 and off dynamically... 1606 Another amusing thing one can do is use Xvfb as the X server, e.g. 1607 "xinit $HOME/.xinitrc -- /usr/X11R6/bin/Xvfb :1 -screen 0 1608 1024x768x16" x11vnc can poll Xvfb efficiently via main memory. 1609 It's not exactly clear why one would want to do this instead of 1610 using vncserver/Xvnc, (perhaps to take advantage of an x11vnc 1611 feature, such as framebuffer scaling or built-in SSL encryption), 1612 but we mention it because it may be of use for special purpose 1613 applications. You may need to use the "-cc 4" option to force Xvfb 1614 to use a TrueColor visual instead of DirectColor. See also the 1615 description of the -create option that does all of this 1616 automatically for you (be sure to install the Xvfb package, e.g. 1617 apt-get install xvfb.) 1618 Also, a faster and more accurate way is to use the "dummy" 1619 Xorg/XFree86 device driver (or our Xdummy wrapper script.) See 1620 this FAQ for details. 1621 * Somewhat surprisingly, the X11 mouse (cursor) shape is write-only 1622 and cannot be queried from the X server. So traditionally in 1623 x11vnc the cursor shape stays fixed at an arrow. (see the "-cursor 1624 X" and "-cursor some" options, however, for a partial hack for the 1625 root window, etc.) However, on Solaris using the SUN_OVL overlay 1626 extension, x11vnc can show the correct mouse cursor when the 1627 -overlay option is also supplied. A similar thing is done on IRIX 1628 as well when -overlay is supplied. 1629 More generally, as of Dec/2004 x11vnc supports the new XFIXES 1630 extension (in Xorg and Solaris 10) to query the X server for the 1631 exact cursor shape, this works pretty well except that cursors 1632 with transparency (alpha channel) need to approximated to solid 1633 RGB values (some cursors look worse than others.) 1634 * Audio from applications is of course not redirected (separate 1635 redirectors do exist, e.g. esd, see the FAQ on this below.) The 1636 XBell() "beeps" will work if the X server supports the XKEYBOARD 1637 extension. (Note that on Solaris XKEYBOARD is disabled by default. 1638 Passing +kb to Xsun enables it.) 1639 * The scroll detection algorithm for the -scrollcopyrect option can 1640 give choppy or bunched up transient output and occasionally 1641 painting errors. 1642 * Using -threads can expose some bugs/crashes in libvncserver. 1643 1644 Please feel free to contact me if you have any questions, problems, or 1645 comments about x11vnc, etc. Please be polite, thorough, and not 1646 demanding (sadly, the number of people contacting me that are rude and 1647 demanding is increasing dramatically.) 1648 Also, some people ask if they can make a donation, see this link for 1649 that. 1650 1651 ======================================================================= 1652 http://www.karlrunge.com/x11vnc/faq.html: 1653 1654 1655 x11vnc Home Donations 1656 _________________________________________________________________ 1657 1658 x11vnc FAQ: 1659 1660 1661 [Building and Starting] 1662 1663 Q-1: I can't get x11vnc to start up. It says "XOpenDisplay failed 1664 (null)" or "Xlib: connection to ":0.0" refused by server Xlib: No 1665 protocol specified" and then exits. What do I need to do? 1666 1667 Q-2: I can't get x11vnc and/or libvncserver to compile. 1668 1669 Q-3: I just built x11vnc successfully, but when I use it my keystrokes 1670 and mouse button clicks are ignored (I am able to move the mouse 1671 though.) 1672 1673 Q-4: Help, I need to run x11vnc on Solaris 2.5.1 (or other old 1674 Unix/Linux) and it doesn't compile! 1675 1676 Q-5: Where can I get a precompiled x11vnc binary for my Operating 1677 System? 1678 1679 Q-6: Where can I get a VNC Viewer binary (or source code) for the 1680 Operating System I will be viewing from? 1681 1682 Q-7: How can I see all of x11vnc's command line options and 1683 documentation on how to use them? 1684 1685 Q-8: I don't like typing arcane command line options every time I 1686 start x11vnc. What can I do? Is there a config file? Or a GUI? 1687 1688 Q-9: How can I get the GUI to run in the System Tray, or at least be a 1689 smaller, simpler icon? 1690 1691 Q-10: How can I get x11vnc to listen on a different port besides the 1692 default VNC port (5900)? 1693 1694 Q-11: My Firewall/Router doesn't allow VNC Viewers to connect to 1695 x11vnc. 1696 1697 Q-12: Is it possible for a VNC Viewer and a VNC Server to connect to 1698 each other even though both are behind Firewalls that block all 1699 incoming connections? 1700 1701 Q-13: Can I make x11vnc more quiet and also go into the background 1702 after starting up? 1703 1704 Q-14: Sometimes when a VNC viewer dies abruptly, x11vnc also dies with 1705 the error message like: "Broken pipe". I'm using the -forever mode and 1706 I want x11vnc to keep running. 1707 1708 Q-15: The Windows TightVNC 1.3.9 Viewer cannot connect to x11vnc. 1709 1710 Q-16: KDE's krdc VNC viewer cannot connect to x11vnc. 1711 1712 Q-17: When I start x11vnc on an Alpha Tru64 workstation the X server 1713 crashes! 1714 1715 Q-18: When running x11vnc on an IBM AIX workstation after a few 1716 minutes the VNC connection freezes. 1717 1718 Q-19: Are there any build-time customizations possible, e.g. change 1719 defaults, create a smaller binary, etc? 1720 1721 [Win2VNC Related] 1722 1723 Q-20: I have two separate machine displays in front of me, one Windows 1724 the other X11: can I use x11vnc in combination with Win2VNC in 1725 dual-screen mode to pass the keystrokes and mouse motions to the X11 1726 display? 1727 1728 Q-21: I am running Win2VNC on my Windows machine and "x11vnc -nofb" on 1729 Unix to pass keyboard and mouse to the Unix monitor. Whenever I start 1730 Win2VNC it quickly disconnects and x11vnc says: 1731 rfbProcessClientNormalMessage: read: Connection reset by peer 1732 1733 Q-22: Can I run "x11vnc -nofb" on a Mac OS X machine to redirect mouse 1734 and keyboard input to it from Windows and X11 machines via Win2VNC and 1735 x2vnc, respectively? 1736 1737 [Color Issues] 1738 1739 Q-23: The X display I run x11vnc on is only 8 bits per pixel (bpp) 1740 PseudoColor (i.e. only 256 distinct colors.) The x11vnc colors may 1741 start out OK, but after a while they are incorrect in certain windows. 1742 1743 Q-24: Color problems: Why are the colors for some windows incorrect in 1744 x11vnc? BTW, my X display has nice overlay/multi-depth visuals of 1745 different color depths: e.g. there are both depth 8 and 24 visuals 1746 available at the same time. 1747 1748 Q-25: I am on a high color system (depth >= 24) but I seem to have 1749 colormap problems. They either flash or everything is very dark. 1750 1751 Q-26: How do I figure out the window id to supply to the -id windowid 1752 option? 1753 1754 Q-27: Why don't menus or other transient windows come up when I am 1755 using the -id windowid option to view a single application window? 1756 1757 Q-28: My X display is depth 24 at 24bpp (instead of the normal depth 1758 24 at 32bpp.) I'm having lots of color and visual problems with x11vnc 1759 and/or vncviewer. What's up? 1760 1761 [Xterminals] 1762 1763 Q-29: Can I use x11vnc to view and interact with an Xterminal (e.g. 1764 NCD) that is not running UNIX and so x11vnc cannot be run on it 1765 directly? 1766 1767 Q-30: How do I get my X permissions (MIT-MAGIC-COOKIE file) correct 1768 for a Unix/Linux machine acting as an Xterminal? 1769 1770 [Sun Rays] 1771 1772 Q-31: I'm having trouble using x11vnc with my Sun Ray session. 1773 1774 [Remote Control] 1775 1776 Q-32: How do I stop x11vnc once it is running in the background? 1777 1778 Q-33: Can I change settings in x11vnc without having to restart it? 1779 Can I remote control it? 1780 1781 [Security and Permissions] 1782 1783 Q-34: How do I create a VNC password for use with x11vnc? 1784 1785 Q-35: Can I make it so -storepasswd doesn't show my password on the 1786 screen? 1787 1788 Q-36: Can I have two passwords for VNC viewers, one for full access 1789 and the other for view-only access to the display? 1790 1791 Q-37: Can I have as many full-access and view-only passwords as I 1792 like? 1793 1794 Q-38: Does x11vnc support Unix usernames and passwords? Can I further 1795 limit the set of Unix usernames who can connect to the VNC desktop? 1796 1797 Q-39: Can I supply an external program to provide my own custom login 1798 method (e.g. Dynamic/One-time passwords or non-Unix (LDAP) usernames 1799 and passwords)? 1800 1801 Q-40: Why does x11vnc exit as soon as the VNC viewer disconnects? And 1802 why doesn't it allow more than one VNC viewer to connect at the same 1803 time? 1804 1805 Q-41: Can I limit which machines incoming VNC clients can connect 1806 from? 1807 1808 Q-42: How do I build x11vnc/libvncserver with libwrap (tcp_wrappers) 1809 support? 1810 1811 Q-43: Can I have x11vnc only listen on one network interface (e.g. 1812 internal LAN) rather than having it listen on all network interfaces 1813 and relying on -allow to filter unwanted connections out? 1814 1815 Q-44: Now that -localhost implies listening only on the loopback 1816 interface, how I can occasionally allow in a non-localhost via the -R 1817 allowonce remote control command? 1818 1819 Q-45: Can I fine tune what types of user input are allowed? E.g. have 1820 some users just be able to move the mouse, but not click or type 1821 anything? 1822 1823 Q-46: Can I prompt the user at the local X display whether the 1824 incoming VNC client should be accepted or not? Can I decide to make 1825 some clients view-only? How about running an arbitrary program to make 1826 the decisions? 1827 1828 Q-47: I start x11vnc as root because it is launched via inetd(8) or a 1829 display manager like gdm(1). Can I have x11vnc later switch to a 1830 different user? 1831 1832 Q-48: I use a screen-lock when I leave my workstation (e.g. 1833 xscreensaver or xlock.) When I remotely access my workstation desktop 1834 via x11vnc I can unlock the desktop fine, but I am worried people will 1835 see my activities on the physical monitor. What can I do to prevent 1836 this, or at least make it more difficult? 1837 1838 Q-49: Can I have x11vnc automatically lock the screen when I 1839 disconnect the VNC viewer? 1840 1841 [Encrypted Connections] 1842 1843 Q-50: How can I tunnel my connection to x11vnc via an encrypted SSH 1844 channel between two Unix machines? 1845 1846 Q-51: How can I tunnel my connection to x11vnc via an encrypted SSH 1847 channel from Windows using an SSH client like Putty? 1848 1849 Q-52: How can I tunnel my connection to x11vnc via an encrypted SSL 1850 channel using an external tool like stunnel? 1851 1852 Q-53: Does x11vnc have built-in SSL tunneling? 1853 1854 Q-54: How do I use VNC Viewers with built-in SSL tunneling? 1855 1856 Q-55: How do I use the Java applet VNC Viewer with built-in SSL 1857 tunneling when going through a Web Proxy? 1858 1859 Q-56: Can Apache web server act as a gateway for users to connect via 1860 SSL from the Internet with a Web browser to x11vnc running on their 1861 workstations behind a firewall? 1862 1863 Q-57: Can I create and use my own SSL Certificate Authority (CA) with 1864 x11vnc? 1865 1866 [Display Managers and Services] 1867 1868 Q-58: How can I run x11vnc as a "service" that is always available? 1869 1870 Q-59: How can I use x11vnc to connect to an X login screen like xdm, 1871 GNOME gdm, KDE kdm, or CDE dtlogin? (i.e. nobody is logged into an X 1872 session yet.) 1873 1874 Q-60: Can I run x11vnc out of inetd(8)? How about xinetd(8)? 1875 1876 Q-61: Can I have x11vnc advertise its VNC service and port via mDNS / 1877 Zeroconf (e.g. Avahi) so VNC viewers on the local network can detect 1878 it automatically? 1879 1880 Q-62: Can I have x11vnc allow a user to log in with her UNIX username 1881 and password and then have it find her X session display on that 1882 machine and then attach to it? How about starting an X session if one 1883 cannot be found? 1884 1885 Q-63: Can I have x11vnc restart itself after it terminates? 1886 1887 Q-64: How do I make x11vnc work with the Java VNC viewer applet in a 1888 web browser? 1889 1890 Q-65: Are reverse connections (i.e. the VNC server connecting to the 1891 VNC viewer) using "vncviewer -listen" and vncconnect(1) supported? 1892 1893 Q-66: Can reverse connections be made to go through a Web or SOCKS 1894 proxy or SSH? 1895 1896 Q-67: Can x11vnc provide a multi-user desktop web login service as an 1897 Apache CGI or PHP script? 1898 1899 Q-68: Can I use x11vnc as a replacement for Xvnc? (i.e. not for a real 1900 display, but for a virtual one I keep around.) 1901 1902 Q-69: How can I use x11vnc on "headless" machines? Why might I want 1903 to? 1904 1905 [Resource Usage and Performance] 1906 1907 Q-70: I have lots of memory, but why does x11vnc fail with shmget: 1908 No space left on device or Minor opcode of failed request: 1 1909 (X_ShmAttach)? 1910 1911 Q-71: How can I make x11vnc use less system resources? 1912 1913 Q-72: How can I make x11vnc use MORE system resources? 1914 1915 Q-73: I use x11vnc over a slow link with high latency (e.g. dialup 1916 modem or broadband), is there anything I can do to speed things up? 1917 1918 Q-74: Does x11vnc support the X DAMAGE Xserver extension to find 1919 modified regions of the screen quickly and efficiently? 1920 1921 Q-75: My OpenGL application shows no screen updates unless I supply 1922 the -noxdamage option to x11vnc. 1923 1924 Q-76: When I drag windows around with the mouse or scroll up and down 1925 things really bog down (unless I do the drag in a single, quick 1926 motion.) Is there anything to do to improve things? 1927 1928 Q-77: Why not do something like wireframe animations to avoid the 1929 windows "lurching" when being moved or resized? 1930 1931 Q-78: Can x11vnc try to apply heuristics to detect when a window is 1932 scrolling its contents and use the CopyRect encoding for a speedup? 1933 1934 Q-79: Can x11vnc do client-side caching of pixel data? I.e. so when 1935 that pixel data is needed again it does not have to be retransmitted 1936 over the network. 1937 1938 Q-80: Does x11vnc support TurboVNC? 1939 1940 [Mouse Cursor Shapes] 1941 1942 Q-81: Why isn't the mouse cursor shape (the little icon shape where 1943 the mouse pointer is) correct as I move from window to window? 1944 1945 Q-82: When using XFIXES cursorshape mode, some of the cursors look 1946 really bad with extra black borders around the cursor and other cruft. 1947 How can I improve their appearance? 1948 1949 Q-83: In XFIXES mode, are there any hacks to handle cursor 1950 transparency ("alpha channel") exactly? 1951 1952 [Mouse Pointer] 1953 1954 Q-84: Why does the mouse arrow just stay in one corner in my 1955 vncviewer, whereas my cursor (that does move) is just a dot? 1956 1957 Q-85: Can I take advantage of the TightVNC extension to the VNC 1958 protocol where Cursor Positions Updates are sent back to all connected 1959 clients (i.e. passive viewers can see the mouse cursor being moved 1960 around by another viewer)? 1961 1962 Q-86: Is it possible to swap the mouse buttons (e.g. left-handed 1963 operation), or arbitrarily remap them? How about mapping button clicks 1964 to keystrokes, e.g. to partially emulate Mouse wheel scrolling? 1965 1966 [Keyboard Issues] 1967 1968 Q-87: How can I get my AltGr and Shift modifiers to work between 1969 keyboards for different languages? 1970 1971 Q-88: When I try to type a "<" (i.e. less than) instead I get ">" 1972 (i.e. greater than)! Strangely, typing ">" works OK!! 1973 1974 Q-89: Extra Character Inserted, E.g.: When I try to type a "<" (i.e. 1975 less than) instead I get "<," (i.e. an extra comma.) 1976 1977 Q-90: I'm using an "international" keyboard (e.g. German "de", or 1978 Danish "dk") and the -modtweak mode works well if the VNC viewer is 1979 run on a Unix/Linux machine with a similar keyboard. But if I run 1980 the VNC viewer on Unix/Linux with a different keyboard (e.g. "us") or 1981 Windows with any keyboard, I can't type some keys like: "@", "$", 1982 "<", ">", etc. How can I fix this? 1983 1984 Q-91: When typing I sometimes get double, triple, or more of my 1985 keystrokes repeated. I'm sure I only typed them once, what can I do? 1986 1987 Q-92: The x11vnc -norepeat mode is in effect, but I still get repeated 1988 keystrokes!! 1989 1990 Q-93: After using x11vnc for a while, I find that I cannot type some 1991 (or any) characters or my mouse clicks and drags no longer have any 1992 effect, or they lead to strange effects. What happened? 1993 1994 Q-94: The machine where I run x11vnc has an AltGr key, but the local 1995 machine where I run the VNC viewer does not. Is there a way I can map 1996 a local unused key to send an AltGr? How about a Compose key as well? 1997 1998 Q-95: I have a Sun machine I run x11vnc on. Its Sun keyboard has just 1999 one Alt key labelled "Alt" and two Meta keys labelled with little 2000 diamonds. The machine where I run the VNC viewer only has Alt keys. 2001 How can I send a Meta keypress? (e.g. emacs needs this) 2002 2003 Q-96: Running x11vnc on HP-UX I cannot type "#" I just get a "3" 2004 instead. 2005 2006 Q-97: Can I map a keystroke to a mouse button click on the remote 2007 machine? 2008 2009 Q-98: How can I get Caps_Lock to work between my VNC viewer and 2010 x11vnc? 2011 2012 [Screen Related Issues and Features] 2013 2014 Q-99: The remote display is larger (in number of pixels) than the 2015 local display I am running the vncviewer on. I don't like the 2016 vncviewer scrollbars, what I can do? 2017 2018 Q-100: Does x11vnc support server-side framebuffer scaling? (E.g. to 2019 make the desktop smaller.) 2020 2021 Q-101: Does x11vnc work with Xinerama? (i.e. multiple monitors joined 2022 together to form one big, single screen.) 2023 2024 Q-102: Can I use x11vnc on a multi-headed display that is not Xinerama 2025 (i.e. separate screens :0.0, :0.1, ... for each monitor)? 2026 2027 Q-103: Can x11vnc show only a portion of the display? (E.g. for a 2028 special purpose application or a very large screen.) 2029 2030 Q-104: Does x11vnc support the XRANDR (X Resize, Rotate and 2031 Reflection) extension? Whenever I rotate or resize the screen x11vnc 2032 just seems to crash. 2033 2034 Q-105: Independent of any XRANDR, can I have x11vnc rotate and/or 2035 reflect the screen that the VNC viewers see? (e.g. for a handheld 2036 whose screen is rotated 90 degrees.) 2037 2038 Q-106: Why is the view in my VNC viewer completely black? Or why is 2039 everything flashing around randomly? 2040 2041 Q-107: I use Linux Virtual Terminals (VT's) to implement 'Fast User 2042 Switching' between users' sessions (e.g. Betty is on Ctrl-Alt-F7, 2043 Bobby is on Ctrl-Alt-F8, and Sid is on Ctrl-Alt-F1: they use those 2044 keystrokes to switch between their sessions.) How come the view in a 2045 VNC viewer connecting to x11vnc is either completely black or 2046 otherwise all messed up unless the X session x11vnc is attached to is 2047 in the active VT? 2048 2049 Q-108: I am using x11vnc where my local machine has "popup/hidden 2050 taskbars" and the remote display where x11vnc runs also has 2051 "popup/hidden taskbars" and they interfere and fight with each other. 2052 What can I do? 2053 2054 Q-109: Help! x11vnc and my KDE screensaver keep switching each other 2055 on and off every few seconds. 2056 2057 Q-110: I am running the compiz 3D window manager (or beryl, MythTv, 2058 Google Earth, or some other OpenGL app) and I do not get screen 2059 updates in x11vnc. 2060 2061 Q-111: Can I use x11vnc to view my VMWare session remotely? 2062 2063 [Exporting non-X11 devices via VNC] 2064 2065 Q-112: Can non-X devices (e.g. a raw framebuffer) be viewed (and even 2066 controlled) via VNC with x11vnc? 2067 2068 Q-113: Can I export the Linux Console (Virtual Terminals) via VNC 2069 using x11vnc? 2070 2071 Q-114: Can I export via VNC a Webcam or TV tuner framebuffer using 2072 x11vnc? 2073 2074 Q-115: Can I connect via VNC to a Qt-embedded/Qt-enhanced/Qtopia 2075 application running on my handheld, cell phone, or PC using the Linux 2076 console framebuffer (i.e. not X11)? 2077 2078 Q-116: How do I inject touch screen input into an 2079 Qt-embedded/Qt-enhanced/Qtopia cell phone such as openmoko/qtmoko Neo 2080 Freerunner? 2081 2082 Q-117: Now that non-X11 devices can be exported via VNC using x11vnc, 2083 can I build it with no dependencies on X11 header files and libraries? 2084 2085 Q-118: How do I cross compile x11vnc for a different architecture than 2086 my Linux i386 or amd64 PC? 2087 2088 Q-119: Does x11vnc support Mac OS X Aqua/Quartz displays natively 2089 (i.e. no X11 involved)? 2090 2091 Q-120: Can x11vnc be used as a VNC reflector/repeater to improve 2092 performance for the case of a large number of simultaneous VNC viewers 2093 (e.g. classroom broadcasting or a large demo)? 2094 2095 Q-121: Can x11vnc be used during a Linux, Solaris, etc. system 2096 Installation so the Installation can be done remotely? 2097 2098 [Misc: Clipboard, File Transfer/Sharing, Printing, Sound, Beeps, 2099 Thanks, etc.] 2100 2101 Q-122: Does the Clipboard/Selection get transferred between the 2102 vncviewer and the X display? 2103 2104 Q-123: Can I use x11vnc to record a Shock Wave Flash (or other format) 2105 video of my desktop, e.g. to record a tutorial or demo? 2106 2107 Q-124: Can I transfer files back and forth with x11vnc? 2108 2109 Q-125: Which UltraVNC extensions are supported? 2110 2111 Q-126: Can x11vnc emulate UltraVNC's Single Click helpdesk mode for 2112 Unix? I.e. something very simple for a naive user to initiate a 2113 reverse vnc connection from their Unix desktop to a helpdesk 2114 operator's VNC Viewer. 2115 2116 Q-127: Can I (temporarily) mount my local (viewer-side) Windows/Samba 2117 File share on the machine where x11vnc is running? 2118 2119 Q-128: Can I redirect CUPS print jobs from the remote desktop where 2120 x11vnc is running to a printer on my local (viewer-side) machine? 2121 2122 Q-129: How can I hear the sound (audio) from the remote applications 2123 on the desktop I am viewing via x11vnc? 2124 2125 Q-130: Why don't I hear the "Beeps" in my X session (e.g. when typing 2126 tput bel in an xterm)? 2127 2128 Q-131: Does x11vnc work with IPv6? 2129 2130 Q-132: Thanks for your program or for your help! Can I make a 2131 donation? 2132 _________________________________________________________________ 2133 2134 2135 [Building and Starting] 2136 2137 Q-1: I can't get x11vnc to start up. It says "XOpenDisplay failed 2138 (null)" or "Xlib: connection to ":0.0" refused by server Xlib: No 2139 protocol specified" and then exits. What do I need to do? 2140 2141 For the former error, you need to specify the X display to connect to 2142 (it also needs to be on the same machine the x11vnc process is to run 2143 on.) Set your DISPLAY environment variable (or use the -display 2144 option) to specify it. Nearly always the correct value will be ":0" 2145 (in fact, x11vnc will now assume :0 if given no other information.) 2146 2147 2148 For the latter error, you need to set up the X11 permissions 2149 correctly. 2150 2151 To make sure X11 permissions are the problem do this simple test: 2152 while sitting at the physical X display open a terminal window 2153 (gnome-terminal, xterm, etc.) You should be able to run x11vnc 2154 successfully without any need for special steps or command line 2155 options in that terminal (i.e. just type "x11vnc".) If that works OK 2156 then you know X11 permissions are the only thing preventing it from 2157 working when you try to start x11vnc via, say, a remote shell. 2158 2159 How to Solve: See the xauth(1), Xsecurity(7), and xhost(1) man pages 2160 or this Howto for much info on X11 permissions. For example, you may 2161 need to set your XAUTHORITY environment variable (or use the -auth 2162 option) to point to the correct MIT-MAGIC-COOKIE file (e.g. 2163 /home/joe/.Xauthority or /var/gdm/:0.Xauth or /var/lib/kdm/A:0-crWk72K 2164 or /tmp/.gdmzndVlR, etc, etc.), or simply be sure you run x11vnc as 2165 the correct user (i.e. the user who is logged into the X session you 2166 wish to view.) 2167 2168 Note: The MIT cookie file contains the secret key that allows x11vnc 2169 to connect to the desired X display. 2170 2171 If, say, sshd has set XAUTHORITY to point to a random file it has 2172 created for X forwarding that will cause problems. (Under some 2173 circumstances even su(1) and telnet(1) can set XAUTHORITY. See also 2174 the gdm parameter NeverPlaceCookiesOnNFS that sets XAUTHORITY to a 2175 random filename in /tmp for the whole X session.) 2176 2177 Running x11vnc as root is often not enough: you need to know where the 2178 MIT-MAGIC-COOKIE file for the desired X display is. 2179 2180 Example solution: 2181 x11vnc -display :0 -auth /var/gdm/:0.Xauth 2182 2183 (this is for the display manager gdm and requires root permission to 2184 read the gdm cookie file, see this faq for other display manager 2185 cookie file names.) 2186 2187 Note as of Feb/2007 you can also try the -find option instead of 2188 "-display ..." and see if that finds your display and Xauthority. 2189 2190 Less safe, but to avoid figuring out where the correct XAUTHORITY file 2191 is, if the person sitting at the physical X session types "xhost 2192 +localhost" then one should be able to attach x11vnc to the session 2193 (from the same machine.) The person could then type "xhost -localhost" 2194 after x11vnc has connected to go back to the default permissions. 2195 Also, for some situations the "-users lurk=" option may soon be of use 2196 (please read the documentation on the -users option.) 2197 2198 To test out your X11 permissions from a remote shell, set DISPLAY and 2199 possibly XAUTHORITY (see your shell's man page, bash(1), tcsh(1), on 2200 how to set environment variables) and type xdpyinfo in the same place 2201 you will be typing (or otherwise running) x11vnc. If information is 2202 printed out about the X display (screen sizes, supported extensions, 2203 color visuals info) that means the X11 permissions are set up 2204 properly: xdpyinfo successfully connected to DISPLAY! You could also 2205 type xclock and make sure no errors are reported (a clock should 2206 appear on the X display, press Ctrl-C to stop it.) If these work, then 2207 typing "x11vnc" in the same environment should also work. 2208 2209 Important: if you cannot get your X11 permissions so that the xdpyinfo 2210 or xclock tests work, x11vnc also will not work (all of these X 2211 clients must be allowed to connect to the X server to function 2212 properly.) 2213 2214 Firewalls: Speaking of permissions, it should go without saying that 2215 the host-level firewall will need to be configured to allow 2216 connections in on a port. E.g. 5900 (default VNC port) or 22 (default 2217 SSH port for tunnelling VNC.) Most systems these days have firewalls 2218 turned on by default, so you will actively have to do something to 2219 poke a hole in the firewall at the desired port number. See your 2220 system administration tool for Firewall settings (Yast, Firestarter, 2221 etc.) 2222 2223 2224 Q-2: I can't get x11vnc and/or libvncserver to compile. 2225 2226 Make sure you have gcc (or other C compiler) and all of the required 2227 libraries and the corresponding -dev/-devel packages installed. These 2228 include Xorg/XFree86, libX11, libjpeg, libz, libssl, ... and don't 2229 forget the devs: libjpeg-dev, libssl-dev ... 2230 2231 The most common build problem that people encounter is that the 2232 necessary X11 libraries are installed on their system however it does 2233 not have the corresponding -dev/-devel packages installed. These dev 2234 packages include C header files and build-time .so symlink. It is a 2235 shame the current trend in distros is to not install the dev package 2236 by default when the the library runtime package is installed... (it 2237 diminishes the power of open source) 2238 2239 As of Nov/2006 here is a list of libraries that x11vnc usually likes 2240 to use: 2241 libc.so libX11.so libXtst.so libXext.so 2242 libXfixes.so libXdamage.so libXinerama.so libXrandr.so 2243 libz.so libjpeg.so libpthread.so 2244 libssl.so libcrypto.so libcrypt.so 2245 2246 although x11vnc will be pretty usable with the subset: libc.so, 2247 libX11.so, libXtst.so, libXext.so, libz.so, and libjpeg.so. 2248 2249 After running the libvncserver configure, carefully examine the output 2250 and the messages in the config.log file looking for missing 2251 components. For example, if the configure output looks like: 2252 checking how to run the C preprocessor... gcc -E 2253 checking for X... no 2254 checking for XkbSelectEvents in -lX11... no 2255 checking for XineramaQueryScreens in -lXinerama... no 2256 checking for XTestFakeKeyEvent in -lXtst... no 2257 2258 or even worse: 2259 checking for C compiler default output file name... configure: error: 2260 C compiler cannot create executables 2261 See `config.log' for more details. 2262 2263 there is quite a bit wrong with the build environment. Hopefully 2264 simply adding -dev packages and/or gcc or make will fix it. 2265 2266 For Debian the list seems to be: 2267 gcc 2268 make 2269 libc6-dev 2270 libjpeg8-dev (formerly libjpeg62-dev) 2271 libx11-dev 2272 x11proto-core-dev (formerly x-dev) 2273 libxext-dev 2274 libxtst-dev 2275 libxdamage-dev 2276 libxfixes-dev 2277 libxrandr-dev 2278 libxinerama-dev 2279 libxss-dev (formerly xlibs-static-dev) 2280 zlib1g-dev 2281 libssl-dev 2282 libavahi-client-dev 2283 linux-libc-dev (only needed for linux console rawfb support) 2284 2285 Note that depending on your OS version the above names may have been 2286 changed and/or additional packages may be needed. 2287 2288 For Redhat the list seems to be: 2289 gcc 2290 make 2291 glibc-devel 2292 libjpeg-devel 2293 libX11-devel 2294 xorg-x11-proto-devel 2295 libXdamage-devel 2296 libXfixes-devel 2297 libXrandr-devel 2298 zlib-devel 2299 openssl-devel 2300 avahi-devel 2301 kernel-headers (only needed for linux console rawfb support) 2302 2303 For other distros or OS's the package names may not be the same but 2304 will look similar. Also, distros tend to rename packages as well so 2305 the above list may be out of date. So only use the above lists as 2306 hints for the package names that are needed. 2307 2308 Have a look at Misc. Build Problems for additional fixes. 2309 2310 Note: there is growing trend in Linux and other distros to slice up 2311 core X11 software into more and smaller packages. So be prepared for 2312 more headaches compiling software... 2313 2314 2315 Q-3: I just built x11vnc successfully, but when I use it my keystrokes 2316 and mouse button clicks are ignored (I am able to move the mouse 2317 though.) 2318 2319 This is most likely due to you not having a working build environment 2320 for the XTEST client library libXtst.so. The library is probably 2321 present on your system, but the package installing the build header 2322 file is missing. 2323 2324 If you were watching carefully while configure was running you would 2325 have seen: 2326 checking for XTestFakeKeyEvent in -lXtst... no 2327 2328 The solution is to add the necessary build environment package (and 2329 the library package if that is missing too.) On Debian the build 2330 package is libxtst-dev. Other distros/OS's may have it in another 2331 package. 2332 2333 x11vnc will build without support for this library (e.g. perhaps one 2334 wants a view-only x11vnc on a stripped down or embedded system...) And 2335 at runtime it will also continue to run even if the X server it 2336 connects to does not support XTEST. In both cases it cannot inject 2337 keystrokes or button clicks since XTEST is needed for that (it can 2338 still move the mouse pointer using the X API XWarpPointer().) 2339 2340 You will see a warning message something like this at run time: 2341 20/03/2005 22:33:09 WARNING: XTEST extension not available (either missing fr 2342 om 2343 20/03/2005 22:33:09 display or client library libXtst missing at build time 2344 .) 2345 20/03/2005 22:33:09 MOST user input (pointer and keyboard) will be DISCARDE 2346 D. 2347 20/03/2005 22:33:09 If display does have XTEST, be sure to build x11vnc wit 2348 h 2349 20/03/2005 22:33:09 a working libXtst build environment (e.g. libxtst-dev, 2350 20/03/2005 22:33:09 or other packages.) 2351 20/03/2005 22:33:09 No XTEST extension, switching to -xwarppointer mode for 2352 20/03/2005 22:33:09 pointer motion input. 2353 2354 Also, as of Nov/2006 there will be a configure build time warning as 2355 well: 2356 ... 2357 checking for XFixesGetCursorImage in -lXfixes... yes 2358 checking for XDamageQueryExtension in -lXdamage... yes 2359 configure: WARNING: 2360 ========================================================================== 2361 A working build environment for the XTEST extension was not found (libXtst). 2362 An x11vnc built this way will be only barely usable. You will be able to 2363 move the mouse but not click or type. There can also be deadlocks if an 2364 application grabs the X server. 2365 2366 It is recommended that you install the necessary development packages 2367 for XTEST (perhaps it is named something like libxtst-dev) and run 2368 configure again. 2369 ========================================================================== 2370 2371 2372 Q-4: Help, I need to run x11vnc on Solaris 2.5.1 (or other old 2373 Unix/Linux) and it doesn't compile! 2374 2375 We apologize that x11vnc does not build cleanly on older versions of 2376 Solaris, Linux, etc.: very few users are on these old releases. 2377 2378 We have heard that since Dec/2004 a Solaris 2.6 built x11vnc will run 2379 on Solaris Solaris 2.5 and 2.5.1 (since a workaround for XConvertCase 2380 is provided.) 2381 2382 In any event, here is a workaround for Solaris 2.5.1 (and perhaps 2383 earlier and perhaps non-Solaris): 2384 2385 First use the environment settings (CPPFLAGS, LDFLAGS, etc.) in the 2386 above Solaris build script to run the configure command. That should 2387 succeed without failure. Then you have to hand edit the autogenerated 2388 rfb/rfbconfig.h file in the source tree, and just before the last 2389 #endif at the bottom of that file insert these workaround lines: 2390 struct timeval _tmp_usleep_tv; 2391 #define usleep(x) \ 2392 _tmp_usleep_tv.tv_sec = (x) / 1000000; \ 2393 _tmp_usleep_tv.tv_usec = (x) % 1000000; \ 2394 select(0, NULL, NULL, NULL, &_tmp_usleep_tv); 2395 int gethostname(char *name, int namelen); 2396 long random(); 2397 int srandom(unsigned int seed); 2398 #undef LIBVNCSERVER_HAVE_LIBPTHREAD 2399 #define SHUT_RDWR 2 2400 typedef unsigned int in_addr_t; 2401 #define snprintf(a, n, args...) sprintf((a), ## args) 2402 2403 Then run make with the Solaris build script environment, everything 2404 should compile without problems, and the resulting x11vnc binary 2405 should work OK. If some non-x11vnc related programs fail (e.g. test 2406 programs) and the x11vnc binary is not created try "make -k" to have 2407 it keep going. Similar sorts of kludges in rfb/rfbconfig.h can be done 2408 on other older OS (Solaris, Linux, ...) releases. 2409 2410 Here are some notes for similar steps that need to be done to build on 2411 SunOS 4.x 2412 2413 Please let us know if you had to use the above workaround (and whether 2414 it worked or not.) If there is enough demand we will try to push clean 2415 compilations back to earlier Solaris, Linux, etc, releases. 2416 2417 2418 Q-5: Where can I get a precompiled x11vnc binary for my Operating 2419 System? 2420 2421 Hopefully the build steps above and FAQ provide enough info for a 2422 painless compile for most environments. Please report problems with 2423 the x11vnc configure, make, etc. on your system (if your system is 2424 known to compile other GNU packages successfully.) 2425 2426 There are precompiled x11vnc binaries built by other groups that are 2427 available at the following locations: 2428 Slackware: (.tgz) http://www.linuxpackages.net/ 2429 2430 SuSE: (.rpm) http:/software.opensuse.org/ Gentoo: (info) 2431 http://gentoo-wiki.com/ and http://gentoo-portage.com/ FreeBSD: (.tbz) 2432 http://www.freebsd.org/ http://www.freshports.org/net/x11vnc NetBSD: 2433 (src) http://pkgsrc.se/x11/x11vnc OpenBSD: (.tgz) http://openports.se/ 2434 Arch Linux: (.tgz) http://www.archlinux.org/ Nokia 770 (.deb) 2435 http://mike.saunby.googlepages.com/x11vncfornokia7702 Sharp Zaurus 2436 http://www.focv.com/ Debian: (.deb) http://packages.debian.org/x11vnc 2437 Redhat/Fedora: (.rpm) http://packages.sw.be/x11vnc RPMforge 2438 http://dag.wieers.com/rpm/packages/x11vnc/ (N.B.: unmaintained after 2439 0.9.3) Solaris: (pkg) http://www.sunfreeware.com/ 2440 2441 If the above binaries don't work and building x11vnc on your OS fails 2442 (and all else fails!) you can try one of My Collection of x11vnc 2443 Binaries for various OS's and x11vnc releases. 2444 2445 As a general note, the x11vnc program is simple enough you don't 2446 really need to install a package: the binary will in most cases work 2447 as is and from any location (as long as your system libraries are not 2448 too old, etc.) So, for Linux distributions that are not one of the 2449 above, the x11vnc binary from the above packages has a good chance of 2450 working. You can "install" it by just copying the x11vnc binary to the 2451 desired directory in your PATH. Tip on extracting files from a Debian 2452 package: extract the archive via a command like: "ar x 2453 x11vnc_0.6-2_i386.deb" and then you can find the binary in the 2454 resulting data.tar.gz tar file. Also, rpm2cpio(1) is useful in 2455 extracting files from rpm packages. 2456 2457 If you use a standalone binary like this and also want x11vnc to serve 2458 up the Java VNC Viewer jar file (either SSL enabled or regular one), 2459 then you will need to extract the classes subdirectory from the source 2460 tarball and point x11vnc to it via the -httpdir option. E.g.: 2461 x11vnc -httpdir /path/to/x11vnc-0.9.9/classes/ssl ... 2462 2463 2464 Q-6: Where can I get a VNC Viewer binary (or source code) for the 2465 Operating System I will be viewing from? 2466 2467 To obtain VNC viewers for the viewing side (Windows, Mac OS, or Unix) 2468 try here: 2469 * http://www.tightvnc.com/download.html 2470 * http://www.realvnc.com/download-free.html 2471 * http://sourceforge.net/projects/cotvnc/ 2472 * http://www.ultravnc.com/ 2473 * Our Enhanced TightVNC Viewer (SSVNC) 2474 2475 [ssvnc.gif] 2476 2477 2478 Q-7: How can I see all of x11vnc's command line options and 2479 documentation on how to use them? 2480 2481 Run: x11vnc -opts to list just the option names or run: x11vnc 2482 -help for long descriptions about each option. The output is listed 2483 here as well. Yes, x11vnc does have a lot of options, doesn't it... 2484 2485 2486 Q-8: I don't like typing arcane command line options every time I 2487 start x11vnc. What can I do? Is there a config file? Or a GUI? 2488 2489 You could create a shell script that calls x11vnc with your options: 2490 #!/bin/sh 2491 # 2492 # filename: X11vnc (i.e. not "x11vnc") 2493 # It resides in a directory in $PATH. "chmod 755 X11vnc" has been run on it. 2494 # 2495 x11vnc -wait 50 -localhost -rfbauth $HOME/.vnc/passwd -display :0 $* 2496 2497 a similar thing can be done via aliases in your shell (bash, tcsh, 2498 csh, etc..) 2499 2500 Or as of Jun/2004 you can use the simple $HOME/.x11vncrc config file 2501 support. If that file exists, each line is taken as a command line 2502 option. E.g. the above would be: 2503 # this is a comment in my ~/.x11vncrc file 2504 wait 50 # this is a comment to the end of the line. 2505 -localhost # note: the leading "-" is optional. 2506 rfbauth /home/fred/.vnc/passwd 2507 display :0 2508 2509 As of Dec/2004 there is now a simple Tcl/Tk GUI based on the 2510 remote-control functionality ("-R") that was added. The /usr/bin/wish 2511 program is needed for operation. The gui is not particularly 2512 user-friendly, it just provides a point and click mode to set all the 2513 many x11vnc parameters and obtain help on them. It is also very useful 2514 for testing. See the -gui option for more info. Examples: "x11vnc ... 2515 -gui" and "x11vnc ... -gui other:0" in the latter case the gui is 2516 displayed on other:0, not the X display x11vnc is polling. There is 2517 also a "-gui tray" system tray mode. 2518 2519 [tkx11vnc.gif] 2520 2521 NOTE: You may need to install the "wish" or "tk" or "tk8.4" package 2522 for the gui mode to work (the package name depends on your OS/distro.) 2523 The tcl/tk "wish" interpreter is used. In debian (and so ubuntu too) 2524 one would run "apt-get install tk" or perhaps "apt-get install tk8.4" 2525 2526 2527 Q-9: How can I get the GUI to run in the System Tray, or at least be a 2528 smaller, simpler icon? 2529 2530 As of Jul/2005 the gui can run in a more friendly small icon mode 2531 "-gui icon" or in the system tray: "-gui tray". It has balloon status, 2532 a simple menu, and a Properities dialog. The full, complicated, gui is 2533 only available under "Advanced". Other improvements were added as 2534 well. Try "Misc -> simple_gui" for a gui with fewer esoteric menu 2535 items. 2536 2537 If the gui fails to embed itself in the system tray, do a retry via 2538 "Window View -> icon" followed by "Window View -> tray" with the popup 2539 menu. 2540 2541 For inexperienced users starting up x11vnc and the GUI while sitting 2542 at the physical X display (not remotely), using something like "x11vnc 2543 -display :0 -gui tray=setpass" might be something for them that they 2544 are accustomed to in a Desktop environment (it prompts for an initial 2545 password, etc.) This is a basic "Share My Desktop" usage mode. 2546 2547 As of Nov/2008 in x11vnc 0.9.6 there is a desktop menu item 2548 (x11vnc.desktop) that runs this command: 2549 x11vnc -gui tray=setpass -rfbport PROMPT -logfile %HOME/.x11vnc.log.%VNCDISP 2550 LAY 2551 2552 which also prompts for which VNC port to use and a couple other 2553 parameters. 2554 2555 2556 Q-10: How can I get x11vnc to listen on a different port besides the 2557 default VNC port (5900)? 2558 2559 Use something like, e.g., "x11vnc -rfbport 5901" to force it to use 2560 port 5901 (this is VNC display :1.) If something else is using that 2561 port x11vnc will exit immediately. If you do not supply the -rfbport 2562 option, it will autoprobe starting at 5900 and work its way up to 5999 2563 looking for a free port to listen on. In that case, watch for the 2564 PORT=59xx line to see which port it found, then subtract 5900 from it 2565 for the VNC display number to enter into the VNC Viewer(s). 2566 2567 The "-N" option will try to match the VNC display number to the X 2568 display (e.g. X11 DISPLAY of :5 (port 6005) will have VNC display :5 2569 (port 5905).) 2570 2571 Also see the "-autoport n" option to indicated at which value the auto 2572 probing should start at. 2573 2574 2575 Q-11: My Firewall/Router doesn't allow VNC Viewers to connect to 2576 x11vnc. 2577 2578 See the Firewalls/Routers discussion. 2579 2580 2581 Q-12: Is it possible for a VNC Viewer and a VNC Server to connect to 2582 each other even though both are behind Firewalls that block all 2583 incoming connections? 2584 2585 This is very difficult or impossible to do unless a third machine, 2586 reachable by both, is used as a relay. So we assume a third machine is 2587 somehow being used as a relay. 2588 2589 (Update: It may be possible to do "NAT-2-NAT" without a relay machine 2590 by using a UDP tunnel such as http://samy.pl/pwnat/. All that is 2591 required is that both NAT firewalls allow in UDP packets from an IP 2592 address to which a UDP packet has recently been sent to. If you try it 2593 out let us know how it went.) 2594 2595 In the following discussion, we will suppose port 5950 is being used 2596 on the relay machine as the VNC port for the rendezvous. 2597 2598 A way to rendezvous is to have the VNC Server start a reverse 2599 connection to the relay machine: 2600 x11vnc -connect third-machine.net:5950 ... 2601 2602 and the VNC viewer forward connects as usual: 2603 vncviewer third-machine.net:50 2604 2605 Or maybe two ports would be involved, e.g. the viewer goes to display 2606 :51 (5951.) It depends on the relay software being used. 2607 2608 What software to run on third-machine? A TCP relay of some sort could 2609 be used... Try a google search on "tcp relay" or "ip relay". However, 2610 note that this isn't a simple redirection because it hooks up two 2611 incoming connections. You can look at our UltraVNC repeater 2612 implementation ultravnc_repeater.pl for ideas and possibly to 2613 customize. 2614 2615 Also, if you are not the admin of third-machine you'd have to convince 2616 the owner to allow you to install this software (and he would likely 2617 need to open his server's firewall to allow the port through.) 2618 2619 It is recommended that SSL is used for encryption (e.g. "-ssl SAVE") 2620 when going over the internet. 2621 2622 We have a prototype for performing a rendezvous via a Web Server 2623 acting as the relay machine. Download the vncxfer CGI script and see 2624 the instructions at the top. 2625 2626 Once that CGI script is set up on the website, both users go to, say, 2627 http://somesite.com/vncxfer (or maybe a "/cgi-bin" directory or ".cgi" 2628 suffix must be used.) Previously, both have agreed on the same session 2629 name (say by phone or email) , e.g. "5cows", and put that into the 2630 entry form on the vncxfer starting page (hopefully separated by a few 2631 seconds, so the relay helper can fully start up at the first request.) 2632 2633 The page returned tells them the hostname and port number and possible 2634 command to use for forward (VNC Viewer) and reverse (VNC Server, i.e. 2635 x11vnc) connections as described above. 2636 2637 Also since Oct/2007, x11vnc can connect directly (no web browser), 2638 like this: 2639 x11vnc ... -connect localhost:0 -proxy 'http://somesite.com/vncxfer?session= 2640 5cows&' 2641 2642 Unfortunately the prototype requires that the Web server's firewall 2643 allow in the port (e.g. 5950) used for the rendezvous. Most web 2644 servers are not configured to do this, so you would need to ask the 2645 admin to do this for you. Nearly all free webspace sites, e.g. 2646 www.zendurl.com, will not allow your CGI script to be an open relay 2647 like this. (If you find one that does allow this, let me know!) 2648 2649 Maybe someday a clever trick will be thought up to relax the listening 2650 port requirement (e.g. use HTTP/CGI itself for the transfer... it is 2651 difficult to emulate a full-duplex TCP connection with them.) 2652 2653 See also the Firewalls/Routers discussion and Reverse Connection Proxy 2654 discussion. 2655 2656 2657 SSH method: If both users (i.e. one on Viewer-side and the other on 2658 x11vnc server side) have SSH access to a common machine on the 2659 internet (or otherwise mutually reachable), then SSH plumbing can be 2660 used to solve this problem. The users create SSH tunnels going through 2661 the SSH login machine. 2662 2663 Instead of assuming port 5900 is free on the SSH machine, we will 2664 assume both users agreed to use 5933. This will illustrate how to use 2665 a different port for the redir. It could be any port, what matters is 2666 that both parties refer to the same one. 2667 2668 Set up the Tunnel from the VNC Server side: 2669 ssh -t -R 5933:localhost:5900 user (a] third-machine.net 2670 2671 Set up the Tunnel from the VNC Viewer side: 2672 ssh -t -L 5900:localhost:5933 user (a] third-machine.net 2673 2674 Run Server on the VNC Server side: 2675 x11vnc -rfbport 5900 -localhost ... 2676 2677 Run Viewer on the VNC Viewer side: 2678 vncviewer -encodings "copyrect tight zrle hextile" localhost:0 2679 2680 (we assume the old-style -encodings option needs to be used. See here 2681 for details.) 2682 2683 If the SSH machine has been configured (see sshd_config(5)) with the 2684 option GatewayPorts=yes, then the tunnel set up by the VNC Server will 2685 be reachable directly by the VNC viewer (as long as the SSH machine's 2686 firewall does not block the port, 5933 in this example.) So in that 2687 case the Viewer side does not need to run any ssh command, but rather 2688 only runs: 2689 vncviewer third-machine.net:33 2690 2691 In this case we recommend SSL be used for encryption. 2692 2693 The creation of both tunnels can be automated. As of Oct/2007 the -ssh 2694 x11vnc option is available and so only this command needs to be run on 2695 the VNC Server side: 2696 x11vnc -ssh user (a] third-machine.net:33 ... 2697 2698 (the SSH passphrase may need to be supplied.) 2699 2700 To automate on the VNC Viewer side, the user can use the Enhanced 2701 TightVNC Viewer (SSVNC) by: 2702 * Clicking on 'Use SSH' 2703 * Entering user (a] third-machine.net:33 into 'VNC Host:Display' entry 2704 box 2705 * Clicking on 'Connect' 2706 2707 As above, if the SSH GatewayPorts=yes setting is configured the Viewer 2708 side doesn't need to create a SSH tunnel. In SSVNC the Viewer user 2709 could instead select 'Use SSL' and then, e.g., on the Server side 2710 supply "-ssl SAVE" to x11vnc. Then end-to-end SSL encryption would be 2711 used (in addition to the SSH encryption on the Server-side leg.) 2712 2713 2714 Q-13: Can I make x11vnc more quiet and also go into the background 2715 after starting up? 2716 2717 Use the -q and -bg options, respectively. (also: -quiet is an alias 2718 for -q) 2719 2720 Note that under -bg the stderr messages will be lost unless you use 2721 the "-o logfile" option. 2722 2723 2724 Q-14: Sometimes when a VNC viewer dies abruptly, x11vnc also dies with 2725 the error message like: "Broken pipe". I'm using the -forever mode and 2726 I want x11vnc to keep running. 2727 2728 As of Jan/2004 the SIGPIPE signal is ignored. So if a viewer client 2729 terminates abruptly, libvncserver will notice on the next I/O 2730 operation and will close the connection and continue on. 2731 2732 Up until of Apr/2004 the above fix only works for BSD signal systems 2733 (Linux, FreeBSD, ...) For SYSV systems there is a workaround in place 2734 since about Jun/2004. 2735 2736 2737 Q-15: The Windows TightVNC 1.3.9 Viewer cannot connect to x11vnc. 2738 2739 This appears to be fixed in x11vnc version 0.9 and later. If you need 2740 to use an earlier version of x11vnc, try using the "-rfbversion 3.7" 2741 option. In general sometimes one can get a misbehaving viewer to work 2742 by supplying rfb versions 3.7 or 3.3. 2743 2744 2745 Q-16: KDE's krdc VNC viewer cannot connect to x11vnc. 2746 2747 This has been fixed in x11vnc version 0.8.4. More info here, here, and 2748 here. 2749 2750 2751 Q-17: When I start x11vnc on an Alpha Tru64 workstation the X server 2752 crashes! 2753 2754 This is a bug in the X server obviously; an X client should never be 2755 able to crash it. 2756 2757 The problem seems to be with the RECORD X extension and so a 2758 workaround is to use the "-noxrecord" x11vnc command line option. 2759 2760 2761 Q-18: When running x11vnc on an IBM AIX workstation after a few 2762 minutes the VNC connection freezes. 2763 2764 One user reports when running x11vnc on AIX 5.3 in his CDE session 2765 after a few minutes or seconds x11vnc will "freeze" (no more updates 2766 being sent, etc.) The freezing appeared to be worse for versions later 2767 than 0.9.2. 2768 2769 The problem seems to be with the RECORD X extension on AIX and so a 2770 workaround is to use the "-noxrecord" x11vnc command line option. The 2771 user found no freezes occurred when using that option. 2772 2773 2774 Q-19: Are there any build-time customizations possible, e.g. change 2775 defaults, create a smaller binary, etc? 2776 2777 There are some options. They are enabled by adding something like 2778 -Dxxxx=1 to the CPPFLAGS environment variable before running configure 2779 (see the build notes for general background.) 2780 /* 2781 * Mar/2006 2782 * Build-time customization via CPPFLAGS. 2783 * 2784 * Summary of options to include in CPPFLAGS for custom builds: 2785 * 2786 * -DVNCSHARED to have the vnc display shared by default. 2787 * -DFOREVER to have -forever on by default. 2788 * -DNOREPEAT=0 to have -repeat on by default. 2789 * -DADDKEYSYMS=0 to have -noadd_keysyms the default. 2790 * 2791 * -DREMOTE_DEFAULT=0 to disable remote-control on by default (-yesremote.) 2792 * -DREMOTE_CONTROL=0 to disable remote-control mechanism completely. 2793 * -DEXTERNAL_COMMANDS=0 to disable the running of all external commands. 2794 * -DFILEXFER=0 disable filexfer. 2795 * 2796 * -DHARDWIRE_PASSWD=... hardwired passwords, quoting necessary. 2797 * -DHARDWIRE_VIEWPASSWD=... 2798 * -DNOPW=1 make -nopw the default (skip warning) 2799 * -DUSEPW=1 make -usepw the default 2800 * -DPASSWD_REQUIRED=1 exit unless a password is supplied. 2801 * -DPASSWD_UNLESS_NOPW=1 exit unless a password is supplied and no -nopw. 2802 * 2803 * -DWIREFRAME=0 to have -nowireframe as the default. 2804 * -DWIREFRAME_COPYRECT=0 to have -nowirecopyrect as the default. 2805 * -DWIREFRAME_PARMS=... set default -wirecopyrect parameters. 2806 * -DSCROLL_COPYRECT=0 to have -noscrollcopyrect as the default. 2807 * -DSCROLL_COPYRECT_PARMS=... set default -scrollcopyrect parameters. 2808 * -DSCALING_COPYRECT=0 2809 * -DXDAMAGE=0 to have -noxdamage as the default. 2810 * -DSKIPDUPS=0 to have -noskip_dups as the default or vice versa. 2811 * 2812 * -DPOINTER_MODE_DEFAULT={0,1,2,3,4} set default -pointer_mode. 2813 * -DBOLDLY_CLOSE_DISPLAY=0 to not close X DISPLAY under -rawfb. 2814 * -DSMALL_FOOTPRINT=1 for smaller binary size (no help, no gui, etc) 2815 * use 2 or 3 for even smaller footprint. 2816 * -DNOGUI do not include the gui tkx11vnc. 2817 * -DPOLL_8TO24_DELAY=N 2818 * -DDEBUG_XEVENTS=1 enable printout for X events. 2819 * 2820 * Set these in CPPFLAGS before running configure. E.g.: 2821 * 2822 * % env CPPFLAGS="-DFOREVER -DREMOTE_CONTROL=0" ./configure 2823 * % make 2824 */ 2825 2826 If other things (e.g. "-I ...") are needed in CPPFLAGS add them as 2827 well. 2828 2829 On some systems is seems you need to set LC_ALL=C for configure to 2830 work properly... 2831 2832 Be careful the following two variables: HARDWIRE_PASSWD and 2833 HARDWIRE_VIEWPASSWD. If set (remember to include the double quotes 2834 around the string), they will be used as default values for the 2835 -passwd and -viewpasswd options. Of course the strings will exist 2836 unobscured in the x11vnc binary: it better not be readable by 2837 unintendeds. Perhaps this is of use in remote access for an embedded 2838 application, etc... 2839 2840 Let us know if more build-time customizations would be useful. 2841 2842 2843 [Win2VNC Related] 2844 2845 Q-20: I have two separate machine displays in front of me, one Windows 2846 the other X11: can I use x11vnc in combination with Win2VNC in 2847 dual-screen mode to pass the keystrokes and mouse motions to the X11 2848 display? 2849 2850 Yes, for best response start up x11vnc with the "-nofb" option 2851 (disables framebuffer polling, and does other optimizations) on the 2852 secondary display (X11) machine. Then start up Win2VNC on the primary 2853 display (Windows) referring it to the secondary display. 2854 2855 This will also work X11 to X11 using x2vnc, however you would probably 2856 just want to avoid VNC and use x2x for that. 2857 2858 For reference, here are some links to Win2VNC-like programs for 2859 multiple monitor setups: 2860 * Original Win2VNC 2861 * Enhanced Win2VNC (broken?) and sourceforge link 2862 * x2vnc 2863 * x2x 2864 * zvnc (MorphOS) 2865 2866 All of them will work with x11vnc (except x2x where it is not needed.) 2867 2868 2869 Q-21: I am running Win2VNC on my Windows machine and "x11vnc -nofb" on 2870 Unix to pass keyboard and mouse to the Unix monitor. Whenever I start 2871 Win2VNC it quickly disconnects and x11vnc says: 2872 rfbProcessClientNormalMessage: read: Connection reset by peer 2873 2874 Is the default visual of the X display you run x11vnc on low color 2875 (e.g. 8 bit per pixel PseudoColor)? (you can run xdpyinfo to check, 2876 look in the "screen" section.) There seems to be a bug in Win2VNC in 2877 that it cannot deal correctly with colormaps (PseudoColor is the most 2878 common example of a visual with a colormap.) 2879 2880 If so, there are a couple options. 1) Can you set the default visual 2881 on your display to be depth 24 TrueColor? Sun machines often have 8+24 2882 overlay/multi-depth visuals, and you can make the default visual depth 2883 24 TrueColor (see fbconfig(1) and Xsun(1).) 2) As of Feb/2004 x11vnc 2884 has the -visual option to allow you to force the framebuffer visual to 2885 whatever you want (this usually messes up the colors unless you are 2886 very clever.) In this case, the option provides a convenient 2887 workaround for the Win2VNC bug: 2888 x11vnc -nofb -visual TrueColor -display :0 ... 2889 2890 So the visual will be set to 8bpp TrueColor and Win2VNC can handle 2891 this. Since Win2VNC does not use the framebuffer data there should be 2892 no problems in doing this. 2893 2894 Q-22: Can I run "x11vnc -nofb" on a Mac OS X machine to redirect mouse 2895 and keyboard input to it from Windows and X11 machines via Win2VNC and 2896 x2vnc, respectively? 2897 2898 Yes, as of Nov/2006 you can. There may be a trick or two you'll need 2899 to do to get the Clipboard exchange between the machines to work. 2900 2901 2902 2903 [Color Issues] 2904 2905 Q-23: The X display I run x11vnc on is only 8 bits per pixel (bpp) 2906 PseudoColor (i.e. only 256 distinct colors.) The x11vnc colors may 2907 start out OK, but after a while they are incorrect in certain windows. 2908 2909 Use the -flashcmap option to have x11vnc watch for changes in the 2910 colormap, and propagate those changes back to connected clients. This 2911 can be slow (since the whole screen must be updated over the network 2912 whenever the colormap changes.) This flashing colormap behavior often 2913 happens if an application installs its own private colormap when the 2914 mouse is in its window. "netscape -install" is a well-known historical 2915 example of this. Consider reconfiguring the system to 16 bpp or depth 2916 24 TrueColor if at all possible. 2917 2918 Also note the option -8to24 (Jan/2006) can often remove the need for 2919 flashing the colormap. Everything is dynamically transformed to depth 2920 24 at 32 bpp using the colormaps. There may be painting errors however 2921 (see the following FAQ for tips on reducing and correcting them.) 2922 2923 In some rare cases (SCO unixware) the -notruecolor option has 2924 corrected colors on 8bpp displays. The red, green, and blue masks were 2925 non-zero in 8bpp PseudoColor on an obscure setup, and this option 2926 corrected the problems. 2927 2928 2929 Q-24: Color problems: Why are the colors for some windows incorrect in 2930 x11vnc? BTW, my X display has nice overlay/multi-depth visuals of 2931 different color depths: e.g. there are both depth 8 and 24 visuals 2932 available at the same time. 2933 2934 You may want to review the previous question regarding 8 bpp 2935 PseudoColor. 2936 2937 On some hardware (Sun/SPARC and SGI), the -overlay option discussed a 2938 couple paragraphs down may solve this for you (you may want to skip to 2939 it directly.) On other hardware the less robust -8to24 option may help 2940 (also discussed below.) 2941 2942 Run xdpyinfo(1) to see what the default visual is and what the depths 2943 of the other visuals are. Does the default visual have a depth of 8 2944 but there are other visuals of depth 24? If it does, can you possibly 2945 re-configure your X server to make a depth 24 visual the default? If 2946 you can do it, this will save you a lot of grief WRT colors and x11vnc 2947 (and for general usage too!) Here is how I do this on an old 2948 Sparcstation 20 running Solaris 9 with SX graphics 2949 xinit -- -dev /dev/fb defclass TrueColor defdepth 24 2950 2951 and it works nicely (note: to log into console from the dtlogin 2952 window, select "Options -> Command Line Login", then login and enter 2953 the above command.) See the -dev section of the Xsun(1) manpage for a 2954 description of the above arguments. If you have root permission, a 2955 more permanent and convenient thing to do is to record the arguments 2956 in a line like: 2957 :0 Local local_uid@console root /usr/openwin/bin/Xsun -dev /dev/fb defclass 2958 TrueColor defdepth 24 2959 2960 in /etc/dt/config/Xservers (copy /usr/dt/config/Xservers.) Also look 2961 at the fbconfig(1) and related manpages (e.g. ffbconfig, m64config, 2962 pgxconfig, SUNWjfb_config, etc ...) for hardware framebuffer settings 2963 that may achieve the same effect. 2964 2965 In general for non-Sun machines, look at the "-cc class" and related 2966 options in your X server manpage (perhaps Xserver(1)), it may allow 2967 modifying the default visual (e.g. "-cc 4", see <X11/X.h> for the 2968 visual class numbers.) On XFree86 some video card drivers (e.g. Matrox 2969 mga) have settings like Option "Overlay" "24,8" to support multi-depth 2970 overlays. For these, use the "-cc 4" X server command line option to 2971 get a depth 24 default visual. 2972 2973 2974 The -overlay mode: Another option is if the system with overlay 2975 visuals is a Sun system running Solaris or SGI running IRIX you can 2976 use the -overlay x11vnc option (Aug/2004) to have x11vnc use the 2977 Solaris XReadScreen(3X11) function to poll the "true view" of the 2978 whole screen at depth 24 TrueColor. XReadDisplay(3X11) is used on 2979 IRIX. This is useful for Legacy applications (older versions of 2980 Cadence CAD apps are mentioned by x11vnc users) that require the 2981 default depth be 8bpp, or the app will use a 8bpp visual even if depth 2982 24 visuals are available, and so the default depth workaround 2983 described in the previous paragraph is not sufficient for these apps. 2984 2985 It seems that Xorg is working toward supporting XReadDisplay(3X11) as 2986 part of the RENDER extension work. When it does support it and 2987 provides a library API x11vnc will be modified to take advantage of 2988 the feature to support -overlay on Linux, *BSD, etc. Until then see 2989 the -8to24 mode below. 2990 2991 Misc. notes on -overlay mode: An amusing by-product of -overlay mode 2992 is that the mouse cursor shape is correct! (i.e. XFIXES is not 2993 needed.) The -overlay mode may be somewhat slower than normal mode due 2994 to the extra framebuffer manipulations that must be performed. Also, 2995 on Solaris there is a bug in that for some popup menus, the windows 2996 they overlap will have painting errors (flashing colors) while the 2997 popup is up (a workaround is to disable SaveUnders by passing -su to 2998 Xsun, e.g. in your /etc/dt/config/Xservers file.) 2999 3000 3001 The -8to24 mode: The -8to24 x11vnc option (Jan/2006) is a kludge to 3002 try to dynamically rewrite the pixel values so that the 8bpp part of 3003 the screen is mapped onto depth 24 TrueColor. This is less robust than 3004 the -overlay mode because it is done by x11vnc outside of the X 3005 server. So only use it on OS's that do not support -overlay. The 3006 -8to24 mode will work if the default visual is depth 24 or depth 8. It 3007 scans for any windows within 3 levels of the root window that are 8bpp 3008 (i.e. legacy application), or in general ones that are not using the 3009 default visual. For the windows it finds it uses XGetSubImage() to 3010 retrieve the pixels values and uses the correct indexed colormap to 3011 create a depth 24 TrueColor view of the whole screen. This depth 24, 3012 32bpp view is exported via VNC. 3013 3014 Even on pure 8bpp displays it can be used as an alternative to 3015 -flashcmap to avoid color flashing completely. 3016 3017 This scheme is approximate and can often lead to painting errors. You 3018 can manually correct most painting errors by pressing 3 Alt_L's in a 3019 row, or by using something like: -fixscreen V=3.0 to automatically 3020 refresh the screen every 3 seconds. Also -fixscreen 8=3.0 has been 3021 added to just refresh the non-default visual parts of the screen. 3022 3023 In general the scheme uses many resources and may give rise to 3024 sluggish behavior. If multiple windows are using different 8bpp 3025 indexed colormaps all but one window may need to be iconified for the 3026 colors to be correct. There are a number of tunable parameters to try 3027 to adjust performance and painting accuracy. The option -8to24 3028 nogetimage can give a nice speedup if the default depth 24 X server 3029 supports hiding the 8bpp bits in bits 25-32 of the framebuffer data. 3030 On very slow machines -8to24 poll=0.2,cachewin=5.0 gives an useful 3031 speedup. See the -8to24 help description for information on tunable 3032 parameters, etc. 3033 3034 3035 Colors still not working correctly? Run xwininfo on the application 3036 with the incorrect colors to verify that the depth of its visual is 3037 different from the default visual depth (gotten from xdpyinfo.) One 3038 possible workaround in this case is to use the -id option to point 3039 x11vnc at the application window itself. If the application is 3040 complicated (lots of toplevel windows and popup menus) this may not be 3041 acceptable, and may even crash x11vnc (but not the application.) See 3042 also -appshare. 3043 3044 It is theoretically possible to solve this problem in general (see 3045 xwd(1) for example), but it does not seem trivial or sufficiently fast 3046 for x11vnc to be able to do so in real time. The -8to24 method does 3047 this approximately and is somewhat usable. Fortunately the -overlay 3048 option works for Solaris machines with overlay visuals where most of 3049 this problem occurs. 3050 3051 3052 Q-25: I am on a high color system (depth >= 24) but I seem to have 3053 colormap problems. They either flash or everything is very dark. 3054 3055 This can happen if the default Visual (use xdpyinfo to list them) is 3056 DirectColor instead of TrueColor. These are both usually used in high 3057 color modes, but whereas TrueColor uses static ramps for the Red, 3058 Green, and Blue components, DirectColor has arbitrary colormaps for 3059 the Red, Green, and Blue Components. Currently x11vnc cannot decode 3060 these colormaps and treats them just like TrueColor. 3061 3062 The only workaround so far is to restart the X server with the "-cc 4" 3063 option to force TrueColor as the default visual (DirectColor is "-cc 3064 5"; see /usr/include/X11/X.h.) The only place we have seen this is 3065 with the virtual framebuffer server Xvfb on Xorg 7.2. So in that case 3066 you probably should restart it with something like this: "Xvfb :1 -cc 3067 4 -screen 0 1280x1024x24". It should be possible for x11vnc to handle 3068 DirectColor, but this hasn't been implemented due to its rare usage. 3069 3070 You may also see this problem on an X display with a TrueColor default 3071 visual where an application chooses a DirectColor visual for its 3072 window(s). It seems the application also needs to install its own 3073 colormap for the visual for the colors to be messed up in x11vnc. One 3074 can make xwud do this for example. 3075 3076 3077 Q-26: How do I figure out the window id to supply to the -id windowid 3078 option? 3079 3080 Run the xwininfo program in a terminal. It will ask you to click on 3081 the desired application window. After clicking, it will print out much 3082 information, including the window id (e.g. 0x6000010.) Also, the 3083 visual and depth of the window printed out is often useful in 3084 debugging x11vnc color problems. 3085 3086 Also, as of Dec/2004 you can use "-id pick" to have x11vnc run 3087 xwininfo(1) for you and after you click the window it extracts the 3088 windowid. Besides "pick" there is also "id:root" to allow you to go 3089 back to root window when doing remote-control. 3090 3091 3092 Q-27: Why don't menus or other transient windows come up when I am 3093 using the -id windowid option to view a single application window? 3094 3095 This is related to the behavior of the XGetImage(3X11) and 3096 XShmGetImage() interfaces regarding backingstore, saveunders, etc. The 3097 way the image is retrieved depends on some aspects of how the X server 3098 maintains the display image data and whether other windows are 3099 clipping or obscuring it. See the XGetImage(3X11) man page for more 3100 details. If you disable BackingStore and SaveUnders in the X server 3101 you should be able to see these transient windows. 3102 3103 If things are not working and you still want to do the single window 3104 polling, try the -sid windowid option ("shifted" windowid.) 3105 3106 Update: as of Nov/2009 in the 0.9.9 x11vnc development tarball, there 3107 is an experimental Application Sharing mode that improves upon the 3108 -id/-sid single window sharing: -appshare (run "x11vnc -appshare 3109 -help" for more info.) It is still very primitive and approximate, but 3110 at least it displays multiple top-level windows. 3111 3112 3113 Q-28: My X display is depth 24 at 24bpp (instead of the normal depth 3114 24 at 32bpp.) I'm having lots of color and visual problems with x11vnc 3115 and/or vncviewer. What's up? 3116 3117 First off, depth 24 at 24bpp (bpp=bits-per-pixel) is fairly uncommon 3118 and can cause problems in general. It also can be slower than depth 24 3119 at 32bpp. You might want to switch to 32bpp (for XFree86 see the 3120 "-fbbpp 32", DefaultFbBpp, FbBpp and related options.) Perhaps you 3121 have 24bpp because the video memory of the machine is low and the 3122 screen wouldn't fit in video RAM at 32bpp. For this case depth 16 at 3123 16bpp might be an acceptable option. 3124 3125 In any event x11vnc should handle depth 24 at 24bpp (although 3126 performance may be slower, and you may need to use the ZRLE encoding 3127 instead of Tight.) There are some caveats involving the viewer 3128 however: 3129 3130 The RealVNC Unix viewer cannot handle 24bpp from the server, it will 3131 say: "main: setPF: not 8, 16 or 32 bpp?" and exit. I have not checked 3132 the RealVNC Windows viewer. 3133 3134 So you need to use the TightVNC Unix viewer. However there are some 3135 problems with that too. It seems libvncserver does not do 24bpp 3136 correctly with the Tight encoding. The colors and screen ultimately 3137 get messed up. So you have to use a different encoding with the 3138 TightVNC vncviewer, try "zlib", "hextile", or one of the other 3139 encodings (e.g. vncviewer -encodings "zlib hextile" ....) I have not 3140 checked the TightVNC or UltraVNC Windows viewers. 3141 3142 It appears the older RealVNC Unix viewers (e.g. 3.3.3 and 3.3.7) can 3143 handle 24bpp from the server, so you may want to use those. They 3144 evidently request 32 bpp and libvncserver obliges. 3145 3146 Update: as of Apr/2006 you can use the -24to32 option to have x11vnc 3147 dynamically transform the 24bpp pixel data to 32bpp. This extra 3148 transformation could slow things down further however. 3149 3150 Now coming the opposite direction if you are running the vncviewer on 3151 the 24bpp display, TightVNC will fail with "Can't cope with 24 3152 bits-per-pixel. Sorry." and RealVNC will fail with "main: Error: 3153 couldn't find suitable pixmap format" so evidently you cannot use 3154 24bpp for the vncviewers to work on that X display. 3155 3156 Note, however, that the Unix viewer in the Enhanced TightVNC Viewer 3157 (SSVNC) project can handle 24bpp X displays. It does this by 3158 requesting a 16bpp pixel format (or 8bpp if the -bgr233 option has 3159 been supplied) from the VNC server, and translates that to 24bpp 3160 locally. 3161 [Xterminals] 3162 3163 Q-29: Can I use x11vnc to view and interact with an Xterminal (e.g. 3164 NCD) that is not running UNIX and so x11vnc cannot be run on it 3165 directly? 3166 3167 You can, but it will likely be very wasteful of network bandwidth 3168 since you will be polling the X display over the network as opposed to 3169 over the local hardware. To do this, run x11vnc on a UNIX machine as 3170 close as possible network-wise (e.g. same switch) to the Xterminal 3171 machine. Use the -display option to point the display to that of the 3172 Xterminal (you'll of course need basic X11 permission to do that) and 3173 finally supply the -noshm option (this enables the polling over the 3174 network.) 3175 3176 If the Xterminal's X display is open to the network for connections, 3177 you might use something like "-display xterm123:0". If you are trying 3178 to do this via an SSH tunnel (assuming you can actually ssh into the 3179 Xterminal) it will be a little tricky (either use the ssh "-R" option 3180 or consider ssh-ing in the other direction.) In all cases the X11 3181 permissions need to allow the connection. 3182 3183 The response will likely be sluggish (maybe only one "frame" per 3184 second.) This mode is not recommended except for "quick checks" of 3185 hard to get to X servers. Use something like "-wait 150" to cut down 3186 on the polling rate. You may also need -flipbyteorder if the colors 3187 get messed up due to endian byte order differences. 3188 3189 Q-30: How do I get my X permissions (MIT-MAGIC-COOKIE file) correct 3190 for a Unix/Linux machine acting as an Xterminal? 3191 3192 If the X display machine is a traditional Xterminal (where the X 3193 server process runs on the Xterminal box, but all of the X client 3194 applications (firefox, etc) run on a central server (aka "terminal 3195 server")), you will need to log into the Xterminal machine (i.e. get a 3196 shell running there) and then start the x11vnc program. If the 3197 Xterminal Linux/Unix machine is stripped down (e.g. no users besides 3198 root) that may be difficult. 3199 3200 The next problem is the login Display Manager (e.g. gdm, kdm), and 3201 hence the MIT-MAGIC-COOKIE auth files, are on the central server and 3202 not on the Xterminal box where the X server and x11vnc processes are. 3203 3204 So unless X permissions are completely turned off (e.g. "xhost +"), to 3205 run the x11vnc process on the Xterminal box the MIT-MAGIC-COOKIE auth 3206 file data (XAUTHORITY or $HOME/.Xauthority) must be accessible by or 3207 copied to the Xterminal. If $HOME/.Xauthority is exported via NFS 3208 (this is insecure of course, but has been going on for decades), then 3209 x11vnc can simply pick it up via NFS (you may need to use the -auth 3210 option to point to the correct file.) Other options include copying 3211 the auth file using scp, or something like: 3212 central-server> xauth nextract - xterm123:0 | ssh xterm123 xauth nmerge - 3213 3214 and then, say, ssh from central-server to xterm123 to start x11vnc. 3215 Here "xterm123" refers to the computer acting as the Xterminal and 3216 "central-server" is the terminal server. You can use "xauth -f 3217 /path/to/cookie-file list" to examine the contents of the cookie(s) in 3218 a file "/path/to/cookie-file". See the xauth(1) manpage for more 3219 details. 3220 3221 If the display name in the cookie file needs to be changed between the 3222 two hosts, see this note on the "xauth add ..." command. 3223 3224 A less secure option is to run something like "xhost +127.0.0.1" while 3225 sitting at the Xterminal box to allow cookie-free local access for 3226 x11vnc. You can run "xhost -127.0.0.1" after x11vnc connects if you 3227 want to go back to the original permissions. 3228 3229 If the Xterminal is really stripped down and doesn't have any user 3230 accounts, NFS, etc. you'll need to contact your system administrator 3231 to set something up. It can be done!!! Some Xterminal projects have 3232 actually enabled "run locally" facilities for the running of an 3233 occasional app more efficiently locally on the Xterminal box (e.g. 3234 realplayer.) 3235 3236 Not recommended, but as a last resort, you could have x11vnc poll the 3237 Xterminal Display over the network. For this you would run a "x11vnc 3238 -noshm ..." process on the central-server (and hope the network admin 3239 doesn't get angry...) 3240 3241 Note: use of Display Manager (gdm, kdm, ...) auth cookie files (i.e. 3242 from /var/..., /tmp/..., or elsewhere) may require modification via 3243 xauth(1) to correctly include the display x11vnc refers to (e.g. 3244 "xauth -f cookie-file add :0 . 45be51ae2ce9dfbacd882ab3ef8e96b1", 3245 where the "45be51..." cookie value was found from an "xauth -f 3246 /path/to/original/cookie-file list") or other reasons. See xauth(1) 3247 manpage for full details on how to transfer an MIT-MAGIC-COOKIE 3248 between machines and displays. 3249 3250 VNCviewer performance on Xterminals: This isn't related to x11vnc on 3251 Xterminals, but we mention it here anyway because of the similar 3252 issues. If you are on an Xterminal and want to use vncviewer to 3253 connect to a VNC server somewhere, then performance would be best if 3254 you ran the viewer on the Xterminal box. Otherwise, (i.e. running the 3255 viewer process on the central-server) all of the vncviewer screen 3256 drawing is done more inefficiently over the network. Something to 3257 consider, especially on a busy network. (BTW, this has all of the 3258 above permission, etc, problems: both vncviewer and x11vnc are X 3259 client apps desired to be run on the Xterminal box.) 3260 3261 [Sun Rays] 3262 3263 Q-31: I'm having trouble using x11vnc with my Sun Ray session. 3264 3265 The Sun Ray technology is a bit like "VNC done in hardware" (the Sun 3266 Ray terminal device, DTU, playing the role of the vncviewer.) 3267 Completely independent of that, the SunRay user's session is still an 3268 X server that speaks the X11 protocol and so x11vnc simply talks to 3269 the X server part to export the SunRay desktop to any place in the 3270 world (i.e. not only to a Sun Ray terminal device), creating a sort of 3271 "Soft Ray". Please see this discussion of Sun Ray issues for solutions 3272 to problems. 3273 3274 Also see the Sun Ray Remote Control Toolkit that uses x11vnc. 3275 3276 [Remote Control] 3277 3278 Q-32: How do I stop x11vnc once it is running in the background? 3279 3280 As of Dec/2004 there is a remote control feature. It can change a huge 3281 number of parameters on the fly: see the -remote and -query options. 3282 To shut down the running x11vnc server just type "x11vnc -R stop". To 3283 disconnect all clients do "x11vnc -R disconnect:all", etc. 3284 3285 If the -forever option has not been supplied, x11vnc will 3286 automatically exit after the first client disconnects. In general if 3287 you cannot use the remote control, then you will have to kill the 3288 x11vnc process This can be done via: "kill NNNNN" (where NNNNN is the 3289 x11vnc process id number found from ps(1)), or "pkill x11vnc", or 3290 "killall x11vnc" (Linux only.) 3291 3292 If you have not put x11vnc in the background via the -bg option or 3293 shell & operator, then simply press Ctrl-C in the shell where x11vnc 3294 is running to stop it. 3295 3296 Potential Gotcha: If somehow your Keypress of Ctrl-C went through 3297 x11vnc to the Xserver that then delivered it to x11vnc it is possible 3298 one or both of the Ctrl or C keys will be left stuck in the pressed 3299 down state in the Xserver. Tapping the stuck key (either via a new 3300 x11vnc or at the physical console) will release it from the stuck 3301 state. If the keyboard seems to be acting strangely it is often fixed 3302 by tapping Ctrl, Shift, and Alt. Alternatively, the -clear_mods option 3303 and -clear_keys option can be used to release pressed keys at startup 3304 and exit. The option -clear_all will also try to unset Caps_Lock, 3305 Num_Lock, etc. 3306 3307 3308 Q-33: Can I change settings in x11vnc without having to restart it? 3309 Can I remote control it? 3310 3311 Look at the -remote (an alias is -R) and -query (an alias is -Q) 3312 options added in Dec/2004. They allow nearly everything to be changed 3313 dynamically and settings to be queried. Examples: "x11vnc -R shared", 3314 "x11vnc -R forever", "x11vnc -R scale:3/4", "x11vnc -Q modtweak", 3315 "x11vnc -R stop", "x11vnc -R disconnect:all", etc.. 3316 3317 These commands do not start a x11vnc server, but rather communicate 3318 with one that is already running. The X display (X11VNC_REMOTE 3319 property) is used as the communication channel, so the X permissions 3320 and DISPLAY must be set up correctly for communication to be possible. 3321 3322 There is also a simple Tcl/Tk gui based on this remote control 3323 mechanism. See the -gui option for more info. You will need to have 3324 Tcl/Tk (i.e. /usr/bin/wish) installed for it to work. It can also run 3325 in the system tray: "-gui tray" or as a standalone small icon window: 3326 "-gui icon". Use "-gui tray=setpass" for a naive user "Share My 3327 Desktop" mode. 3328 3329 [Security and Permissions] 3330 3331 Q-34: How do I create a VNC password for use with x11vnc? 3332 3333 You may already have one in $HOME/.vnc/passwd if you have used, say, 3334 the vncserver program from the regular RealVNC or TightVNC packages 3335 (i.e. launching the Xvnc server.) Otherwise, you could use the 3336 vncpasswd(1) program from those packages. 3337 3338 As of Jun/2004 x11vnc supports the -storepasswd "pass" "file" option, 3339 which is the same functionality of storepasswd. Be sure to quote the 3340 "pass" if it contains shell meta characters, spaces, etc. Example: 3341 x11vnc -storepasswd 'sword*fish' $HOME/myvncpasswd 3342 3343 You then use the password via the x11vnc option: "-rfbauth 3344 $HOME/myvncpasswd" 3345 3346 As of Jan/2006 if you do not supply any arguments: 3347 x11vnc -storepasswd 3348 3349 you will be prompted for a password to save to ~/.vnc/passwd (your 3350 keystrokes when entering the password will not be echoed to the 3351 screen.) If you supply one argument, e.g. "x11vnc -storepasswd 3352 ~/.mypass", the password you are prompted for will be stored in that 3353 file. 3354 3355 x11vnc also has the -passwdfile and -passwd/-viewpasswd plain text 3356 (i.e. not obscured like the -rfbauth VNC passwords) password options. 3357 3358 You can use the -usepw option to automatically use any password file 3359 you have in ~/.vnc/passwd or ~/.vnc/passwdfile (the latter is used 3360 with the -passwdfile option.) 3361 3362 x11vnc -usepw -display :0 ... 3363 3364 If neither file exists you are prompted to store a password in 3365 ~/.vnc/passwd. If a password file cannot be found or created x11vnc 3366 exits immediately. An admin may want to set it up this way for users 3367 who do not know better. 3368 3369 3370 Q-35: Can I make it so -storepasswd doesn't show my password on the 3371 screen? 3372 3373 You can use the vncpasswd program from RealVNC or TightVNC mentioned 3374 above. As of Jan/2006 the -storepasswd option without any arguments 3375 will not echo your password as you type it and save the file to 3376 ~/.vnc/passwd: 3377 # x11vnc -storepasswd 3378 Enter VNC password: 3379 Verify password: 3380 Write password to /home/myname/.vnc/passwd? [y]/n 3381 Password written to: /home/myname/.vnc/passwd 3382 3383 You can also give it an alternate filename, e.g. "x11vnc -storepasswd 3384 ~/.mypass" 3385 3386 3387 Q-36: Can I have two passwords for VNC viewers, one for full access 3388 and the other for view-only access to the display? 3389 3390 Yes, as of May/2004 there is the -viewpasswd option to supply the 3391 view-only password. Note the full-access password option -passwd must 3392 be supplied at the same time. E.g.: -passwd sword -viewpasswd fish. 3393 3394 To avoid specifying the passwords on the command line (where they 3395 could be observed via the ps(1) command by any user) you can use the 3396 -passwdfile option to specify a file containing plain text passwords. 3397 Presumably this file is readable only by you, and ideally it is 3398 located on the machine x11vnc is run on (to avoid being snooped on 3399 over the network.) The first line of this file is the full-access 3400 password. If there is a second line in the file and it is non-blank, 3401 it is taken as the view-only password. (use "__EMPTY__" to supply an 3402 empty one.) 3403 3404 View-only passwords currently do not work for the -rfbauth password 3405 option (standard VNC password storing mechanism.) FWIW, note that 3406 although the output (usually placed in $HOME/.vnc/passwd) by the 3407 vncpasswd or storepasswd programs (or from x11vnc -storepasswd) looks 3408 encrypted they are really just obscured to avoid "casual" password 3409 stealing. It takes almost no skill to figure out how to extract the 3410 plain text passwords from $HOME/.vnc/passwd since it is very 3411 straight-forward to work out what to do from the VNC source code. 3412 3413 3414 Q-37: Can I have as many full-access and view-only passwords as I 3415 like? 3416 3417 Yes, as of Jan/2006 in the libvncserver CVS the -passwdfile option has 3418 been extended to handle as many passwords as you like. You put the 3419 view-only passwords after a line __BEGIN_VIEWONLY__. 3420 3421 You can also easily annotate and comment out passwords in the file. 3422 You can have x11vnc re-read the file dynamically when it is modified. 3423 3424 3425 Q-38: Does x11vnc support Unix usernames and passwords? Can I further 3426 limit the set of Unix usernames who can connect to the VNC desktop? 3427 Update: as of Feb/2006 x11vnc has the -unixpw option that does this 3428 outside of the VNC protocol and libvncserver. The standard su(1) 3429 program is used to validate the user's password. A familiar "login:" 3430 and "Password:" dialog is presented to the user on a black screen 3431 inside the vncviewer. The connection is dropped if the user fails to 3432 supply the correct password in 3 tries or does not send one before a 3433 25 second timeout. Existing clients are view-only during this period. 3434 A list of allowed Unix usernames may also be supplied along with 3435 per-user settings. 3436 3437 There is also the -unixpw_nis option for non-shadow-password 3438 (typically NIS environments, hence the name) systems where the 3439 traditional getpwnam() and crypt() functions are used instead of 3440 su(1). The encrypted user passwords must be accessible to the user 3441 running x11vnc in -unixpw_nis mode, otherwise the logins will always 3442 fail even when the correct password is supplied. See ypcat(1) and 3443 shadow(5). 3444 3445 Two settings are enforced in the -unixpw and -unixpw_nis modes to 3446 provide extra security: the 1) -localhost and 2) -stunnel or -ssl 3447 options. Without these one might send the Unix username and password 3448 data in clear text over the network which is a very bad idea. They can 3449 be relaxed if you want to provide encryption other than stunnel or 3450 -ssl (the constraint is automatically relaxed if SSH_CONNECTION is set 3451 and indicates you have ssh-ed in, however the -localhost requirement 3452 is still enforced.) 3453 3454 The two -unixpw modes have been tested on Linux, Solaris, Mac OS X, 3455 HP-UX, AIX, Tru64, FreeBSD, OpenBSD, and NetBSD. Additional testing is 3456 appreciated. For the last 4 it appears that su(1) will not prompt for 3457 a password if su-ing to oneself. Since x11vnc requires a password 3458 prompt from su, x11vnc forces those logins to fail even when the 3459 correct password is supplied. On *BSD it appears this can be corrected 3460 by removing the pam_self.so entry in /etc/pam.d/su. 3461 3462 3463 Previous older discussion (prior to the -unixpw option): 3464 3465 Until the VNC protocol and libvncserver support this things will be 3466 approximate at best. 3467 3468 One approximate method involves starting x11vnc with the -localhost 3469 option. This basically requires the viewer user to log into the 3470 workstation where x11vnc is running via their Unix username and 3471 password, and then somehow set up a port redirection of his vncviewer 3472 connection to make it appear to emanate from the local machine. As 3473 discussed above, ssh is useful for this: "ssh -L 5900:localhost:5900 3474 user@hostname ..." See the ssh wrapper scripts mentioned elsewhere on 3475 this page. stunnel does this as well. 3476 3477 Of course a malicious user could allow other users to get in through 3478 his channel, but that is a problem with every method. Another thing to 3479 watch out for is a malicious user on the viewer side (where ssh is 3480 running) trying to sneak in through the ssh port redirection there. 3481 3482 Regarding limiting the set of Unix usernames who can connect, the 3483 traditional way would be to further require a VNC password to supplied 3484 (-rfbauth, -passwd, etc) and only tell the people allowed in what the 3485 VNC password is. A scheme that avoids a second password involves using 3486 the -accept option that runs a program to examine the connection 3487 information to determine which user is connecting from the local 3488 machine. That may be difficult to do, but, for example, the program 3489 could use the ident service on the local machine (normally ident 3490 should not be trusted over the network, but on the local machine it 3491 should be accurate: otherwise root has been compromised and so there 3492 are more serious problems! Unfortunately recent Linux distros seem to 3493 provide a random string (MD5 hash?) instead of the username.) An 3494 example script passed in via -accept scriptname that deduces the Unix 3495 username and limits who can be accepted might look something like 3496 this: 3497 #!/bin/sh 3498 if [ "$RFB_CLIENT_IP" != "127.0.0.1" -o "$RFB_SERVER_IP" != "127.0.0.1" ]; then 3499 exit 1 # something fishy... reject it. 3500 fi 3501 user=`echo "$RFB_CLIENT_PORT, $RFB_SERVER_PORT" | nc -w 1 $RFB_CLIENT_IP 113 \ 3502 | grep 'USERID.*UNIX' | head -n 1 | sed -e 's/[\r ]//g' | awk -F: '{pri 3503 nt $4}'` 3504 3505 for okuser in fred barney wilma betty 3506 do 3507 if [ "X$user" = "X$okuser" ]; then 3508 exit 0 # accept it 3509 fi 3510 done 3511 exit 1 # reject it 3512 3513 For this to work with ssh port redirection, the ssh option 3514 UsePrivilegeSeparation must be enabled otherwise the userid will 3515 always be "root". 3516 3517 Here is a similar example based on Linux netstat(1) output: 3518 #!/bin/sh 3519 # 3520 # accept_local_netstat: x11vnc -accept command to accept a local 3521 # vncviewer connection from acceptable users. Linux netstat -nte is used. 3522 3523 PATH=/bin:/usr/bin:$PATH; export PATH; # set to get system utils 3524 3525 allowed="`id -u fred`"; # add more user numbers if desired. 3526 3527 # check required settings 3528 ok=1 3529 if [ "X$allowed" = "X" ]; then 3530 ok=0; # something wrong with allowed list 3531 fi 3532 if [ "X$RFB_CLIENT_IP" != "X127.0.0.1" -o "X$RFB_SERVER_IP" != "X127.0.0.1" ]; 3533 then 3534 ok=0; # connection not over localhost 3535 fi 3536 if [ "$RFB_CLIENT_PORT" -le 0 -o "$RFB_SERVER_PORT" -le 0 ]; then 3537 ok=0; # something wrong with tcp port numbers 3538 fi 3539 if [ "$ok" = 0 ]; then 3540 echo "$0: invalid setting:" 1>&2 3541 env | grep ^RFB | sort 1>&2 3542 exit 1 3543 fi 3544 3545 # Linux netstat -nte: 3546 # Proto Recv-Q Send-Q Local Address Foreign Address State 3547 User Inode 3548 # 0 0 0 RFB_CLIENT RFB_SERVER ESTABLISHED 3549 nnnn .... 3550 # 3551 user=`netstat -nte | grep ESTABLISHED \ 3552 | grep " $RFB_CLIENT_IP:$RFB_CLIENT_PORT *$RFB_SERVER_IP:$RFB_SERVER_P 3553 ORT "` 3554 3555 echo "netstat match: $user" 1>&2 3556 user=`echo "$user" | head -n 1 | sed -e 's/^.*ESTABLISHED/ /' | awk '{print $1} 3557 '` 3558 3559 ok=0 3560 for u in $allowed 3561 do 3562 if [ "X$user" = "X$u" ]; then 3563 ok=1 3564 break 3565 fi 3566 done 3567 3568 if [ "X$ok" = "X1" ]; then 3569 echo "$0: user accepted: '$user'" 1>&2 3570 exit 0 3571 else 3572 echo "$0: user '$user' invalid:" 1>&2 3573 echo "$0: allowed: $allowed" 1>&2 3574 env | grep ^RFB | sort 1>&2 3575 exit 1 3576 fi 3577 3578 3579 Q-39: Can I supply an external program to provide my own custom login 3580 method (e.g. Dynamic/One-time passwords or non-Unix (LDAP) usernames 3581 and passwords)? 3582 Yes, there are several possibilities. For background see the FAQ on 3583 the -accept where an external program may be run to decide if a VNC 3584 client should be allowed to try to connect and log in. If the program 3585 (or local user prompted by a popup) answers "yes", then -accept 3586 proceeds to the normal VNC and x11vnc authentication methods, 3587 otherwise the connection is dropped. 3588 3589 To provide more direct coupling to the VNC client's username and/or 3590 supplied password the following options were added in Sep/2006: 3591 * -unixpw_cmd command 3592 * -passwdfile cmd:command 3593 * -passwdfile custom:command 3594 3595 In each case "command" is an external command run by x11vnc. You 3596 supply it. For example, it may couple to your LDAP system or other 3597 servers you set up. 3598 3599 For -unixpw_cmd the normal -unixpw Login: and Password: prompts are 3600 supplied to the VNC viewer and the strings the client returns are then 3601 piped into "command" as the first two lines of its standard input. If 3602 the command returns success, i.e. exit(0), the VNC client is accepted, 3603 otherwise it is rejected. 3604 3605 For "-passwdfile cmd:command" the command is run and it returns a 3606 password list (like a password file, see the -passwdfile read:filename 3607 mode.) Perhaps a dynamic, one-time password is retrieved from a server 3608 this way. 3609 3610 For "-passwdfile custom:command" one gets complete control over the 3611 VNC challenge-response dialog with the VNC client. x11vnc sends out a 3612 string of random bytes (16 by the VNC spec) and the client returns the 3613 same number of bytes in a way the server can verify only the 3614 authorized user could have created. The VNC protocol specifies DES 3615 encryption with a password. If you are willing to modify the VNC 3616 viewers, you can have it be anything you want, perhaps a less 3617 crackable MD5 hash scheme or one-time pad. Your program will read from 3618 its standard input the size of the challenge-response followed by a 3619 newline, then the challenge bytes followed by the response bytes. If 3620 your command then returns success, i.e. exit(0), the VNC client is 3621 accepted, otherwise it is rejected. 3622 3623 In all cases the "RFB_*" environment variables are set as under 3624 -accept. These variables can provide useful information for the 3625 externally supplied program to use. 3626 3627 3628 Q-40: Why does x11vnc exit as soon as the VNC viewer disconnects? And 3629 why doesn't it allow more than one VNC viewer to connect at the same 3630 time? 3631 3632 These defaults are simple safety measures to avoid someone unknowingly 3633 leaving his X11 desktop exposed (to the internet, say) for long 3634 periods of time. Use the -forever option (aka -many) to have x11vnc 3635 wait for more connections after the first client disconnects. Use the 3636 -shared option to have x11vnc allow multiple clients to connect 3637 simultaneously. 3638 3639 Recommended additional safety measures include using ssh (see above), 3640 stunnel, -ssl, or a VPN to authenticate and encrypt the viewer 3641 connections or to at least use the -rfbauth passwd-file option to use 3642 VNC password protection (or -passwdfile) It is up to YOU to apply 3643 these security measures, they will not be done for you automatically. 3644 3645 3646 Q-41: Can I limit which machines incoming VNC clients can connect 3647 from? 3648 3649 Yes, look at the -allow and -localhost options to limit connections by 3650 hostname or IP address. E.g. 3651 x11vnc -allow 192.168.0.1,192.168.0.2 3652 3653 for those two hosts or 3654 x11vnc -allow 192.168.0. 3655 3656 for a subnet. For individual hosts you can use the hostname instead of 3657 the IP number, e.g.: "-allow snoopy", and "-allow darkstar,wombat". 3658 Note that -localhost achieves the same thing as "-allow 127.0.0.1" 3659 3660 For more control, build libvncserver with libwrap support 3661 (tcp_wrappers) and then use /etc/hosts.allow See hosts_access(5) for 3662 complete details. 3663 3664 3665 Q-42: How do I build x11vnc/libvncserver with libwrap (tcp_wrappers) 3666 support? 3667 3668 Here is one way to pass this information to the configure script: 3669 env CPPFLAGS=-DUSE_LIBWRAP LDFLAGS=-lwrap ./configure 3670 3671 then run make as usual. This requires libwrap and its development 3672 package (tcpd.h) to be installed on the build machine. If additional 3673 CPPFLAGS or LDFLAGS options are needed supply them as well using 3674 quotes. 3675 3676 The resulting x11vnc then uses libwrap/tcp_wrappers for connections. 3677 The service name you will use in /etc/hosts.allow and /etc/hosts.deny 3678 is "vnc", e.g.: 3679 vnc: 192.168.100.3 .example.com 3680 3681 Note that if you run x11vnc out of inetd you do not need to build 3682 x11vnc with libwrap support because the /usr/sbin/tcpd reference in 3683 /etc/inetd.conf handles the tcp_wrappers stuff. 3684 3685 3686 Q-43: Can I have x11vnc only listen on one network interface (e.g. 3687 internal LAN) rather than having it listen on all network interfaces 3688 and relying on -allow to filter unwanted connections out? 3689 3690 As of Mar/2005 there is the "-listen ipaddr" option that enables this. 3691 For ipaddr either supply the desired network interface's IP address 3692 (or use a hostname that resolves to it) or use the string "localhost". 3693 For additional filtering simultaneously use the "-allow host1,..." 3694 option to allow only specific hosts in. 3695 3696 This option is useful if you want to insure that no one can even begin 3697 a dialog with x11vnc from untrusted network interfaces (e.g. ppp0.) 3698 The option -localhost now implies "-listen localhost" since that is 3699 what most people expect it to do. 3700 3701 3702 Q-44: Now that -localhost implies listening only on the loopback 3703 interface, how I can occasionally allow in a non-localhost via the -R 3704 allowonce remote control command? 3705 3706 To do this specify "-allow localhost". Unlike -localhost this will 3707 leave x11vnc listening on all interfaces (but of course only allowing 3708 in local connections, e.g. ssh redirs.) Then you can later run "x11vnc 3709 -R allowonce:somehost" or use to gui to permit a one-shot connection 3710 from a remote host. 3711 3712 3713 Q-45: Can I fine tune what types of user input are allowed? E.g. have 3714 some users just be able to move the mouse, but not click or type 3715 anything? 3716 3717 As of Feb/2005, the -input option allows you to do this. "K", "M", 3718 "B", "C", and "F" stand for Keystroke, Mouse-motion, Button-clicks, 3719 Clipboard, and File-Transfer, respectively. The setting: "-input M" 3720 makes attached viewers only able to move the mouse. "-input KMBC,M" 3721 lets normal clients do everything and enables view-only clients to 3722 move the mouse. 3723 3724 These settings can also be applied on a per-viewer basis via the 3725 remote control mechanism or the GUI. E.g. x11vnc -R input:hostname:M 3726 3727 3728 Q-46: Can I prompt the user at the local X display whether the 3729 incoming VNC client should be accepted or not? Can I decide to make 3730 some clients view-only? How about running an arbitrary program to make 3731 the decisions? 3732 3733 Yes, look at the "-accept command" option, it allows you to specify an 3734 external command that is run for each new client. (use quotes around 3735 the command if it contains spaces, etc.) If the external command 3736 returns 0 (success) the client is accepted, otherwise with any other 3737 return code the client is rejected. See below how to also accept 3738 clients view-only. 3739 3740 The external command will have the RFB_CLIENT_IP environment variable 3741 set to the client's numerical IP address, RFB_CLIENT_PORT its port 3742 number. Similarly for RFB_SERVER_IP and RFB_SERVER_PORT to allow 3743 identification of the tcp virtual circuit. DISPLAY will be set to that 3744 of the X11 display being polled. Also, RFB_X11VNC_PID is set to the 3745 x11vnc process id (e.g. in case you decided to kill it), RFB_CLIENT_ID 3746 will be an id number, and RFB_CLIENT_COUNT the number of other clients 3747 currently connected. RFB_MODE will be "accept". 3748 3749 Built-in Popup Window: As a special case, "-accept popup" will 3750 instruct x11vnc to create its own simple popup window. To accept the 3751 client press "y" or click mouse on the "Yes" button. To reject the 3752 client press "n" or click mouse on the "No" button. To accept the 3753 client View-only, press "v" or click mouse on the "View" button. If 3754 the -viewonly option has been supplied, the "View" action will not be 3755 present: the whole display is view only in that case. 3756 3757 The popup window times out after 120 seconds, to change this behavior 3758 use "-accept popup:N" where N is the number of seconds (use 0 for no 3759 timeout.) More tricks: "-accept popupmouse" will only take mouse click 3760 responses, while "-accept popupkey" will only take keystroke responses 3761 (popup takes both.) After any of the 3 popup keywords you can supply a 3762 position of the window: +N+M, (the default is to center the window) 3763 e.g. -accept popupmouse+10+10. 3764 3765 Also as a special case "-accept xmessage" will run the xmessage(1) 3766 program to prompt the user whether the client should be accepted or 3767 not. This requires that you have xmessage installed and available via 3768 PATH. In case it is not already on your system, the xmessage program 3769 is available at ftp://ftp.x.org/ 3770 (End of Built-in Popup Window:) 3771 3772 To include view-only decisions for the external commands, prefix the 3773 command something like this: "yes:0,no:*,view:3 mycommand ..." This 3774 associates the three actions: yes(accept), no(reject), and 3775 view(accept-view-only), with the numerical return (i.e. exit()) codes. 3776 Use "*" instead of a number to set the default action (e.g. in case 3777 the external command returns an unexpected return code.) 3778 3779 Here is an example -accept script called accept_or_lock. It uses 3780 xmessage and xlock (replace with your screen lock command, maybe it is 3781 "xscreensaver-command -lock", or kdesktop_lock, or "dtaction 3782 LockDisplay".) It will prompt the user at the X display whether to 3783 accept, reject, or accept view-only the client, but if the prompt 3784 times out after 60 seconds the screen is locked and the VNC client is 3785 accepted. This allows the remote access when no one is at the display. 3786 #!/bin/sh 3787 # 3788 # accept_or_lock: prompt user at X display whether to accept an incoming 3789 # VNC connection. If timeout expires, screen is locked 3790 # and the VNC viewer is accepted (allows remote access 3791 # when no one is sitting at the display.) 3792 # 3793 # usage: x11vnc ... -forever -accept 'yes:0,no:*,view:4 accept_or_lock' 3794 # 3795 xmessage -buttons yes:2,no:3,view-only:4 -center \ 3796 -timeout 60 "x11vnc: accept connection from $RFB_CLIENT_IP?" 3797 rc=$? 3798 if [ $rc = 0 ]; then 3799 xlock & # or "xlock -mode blank" for no animations. 3800 sleep 5 3801 exit 0 3802 elif [ $rc = 2 ]; then 3803 exit 0 3804 elif [ $rc = 4 ]; then 3805 exit 4 3806 fi 3807 exit 1 3808 3809 Stefan Radman has written a nice dtksh script dtVncPopup for use in 3810 CDE environments to do the same sort of thing. Information on how to 3811 use it is found at the top of the file. He encourages you to provide 3812 feedback to him to help improve the script. 3813 3814 Note that in all cases x11vnc will block while the external command or 3815 popup is being run, so attached clients will not receive screen 3816 updates, etc during this period. 3817 3818 To run a command when a client disconnects, use the "-gone command" 3819 option. This is for the user's convenience only: the return code of 3820 the command is not interpreted by x11vnc. The same environment 3821 variables are set as in "-accept command" (except that RFB_MODE will 3822 be "gone".) 3823 3824 As of Jan/2006 the "-afteraccept command" option will run the command 3825 only after the VNC client has been accepted and authenticated. Like 3826 -gone the return code is not interpreted. RFB_MODE will be 3827 "afteraccept".) 3828 3829 3830 Q-47: I start x11vnc as root because it is launched via inetd(8) or a 3831 display manager like gdm(1). Can I have x11vnc later switch to a 3832 different user? 3833 3834 As of Feb/2005 x11vnc has the -users option that allows things like 3835 this. Please read the documentation on it (also in the x11vnc -help 3836 output) carefully for features and caveats. It's use can often 3837 decrease security unless care is taken. 3838 3839 BTW, a nice use of it is "-users +nobody" that switches to the Unix 3840 user nobody right after connections to the X display are established. 3841 3842 In any event, while running x11vnc as root, remember it comes with no 3843 warranty ;-). 3844 3845 3846 Q-48: I use a screen-lock when I leave my workstation (e.g. 3847 xscreensaver or xlock.) When I remotely access my workstation desktop 3848 via x11vnc I can unlock the desktop fine, but I am worried people will 3849 see my activities on the physical monitor. What can I do to prevent 3850 this, or at least make it more difficult? 3851 3852 Probably most work environments would respect your privacy if you 3853 powered off the monitor. Also remember if people have physical access 3854 to your workstation they basically can do anything they want with it 3855 (e.g. install a backdoor for later use, etc.) 3856 3857 In any event, as of Jun/2004 there is an experimental utility to make 3858 it more difficult for nosey people to see your x11vnc activities. The 3859 source for it is blockdpy.c The idea behind it is simple (but 3860 obviously not bulletproof): when a VNC client attaches to x11vnc put 3861 the display monitor in the DPMS "off" state, if the DPMS state ever 3862 changes immediately start up the screen-lock program. The x11vnc user 3863 will notice something is happening and think about what to do next 3864 (while the screen is in a locked state.) 3865 3866 This works (or at least has a chance of working) because if the 3867 intruder moves the mouse or presses a key on the keyboard, the monitor 3868 wakes up out of the DPMS off state, and this induces the screen lock 3869 program to activate as soon as possible. Of course there are cracks in 3870 this, the eavesdropper could detach your monitor and insert a non-DPMS 3871 one, and there are race conditions. As mentioned above this is not 3872 bulletproof. A really robust solution would likely require X server 3873 and perhaps even video hardware support. 3874 3875 The blockdpy utility is launched by the -accept option and told to 3876 exit via the -gone option (the vnc client user should obviously 3877 re-lock the screen before disconnecting!) Instructions can be found in 3878 the source code for the utility at the above link. Roughly it is 3879 something like this: 3880 x11vnc ... -accept "blockdpy -bg -f $HOME/.bdpy" -gone "touch $HOME/.bdpy" 3881 3882 but please read the top of the file. 3883 3884 Update: As of Feb/2007 there is some builtin support for this: 3885 -forcedpms and -clientdpms however, they are probably less robust than 3886 the above blockdpy.c scheme, since if the person floods the physical 3887 machine with mouse or pointer input he can usually see flashes of the 3888 screen before the monitor is powered off again. See also the -grabkbd, 3889 -grabptr, and -grabalways options. 3890 3891 3892 Q-49: Can I have x11vnc automatically lock the screen when I 3893 disconnect the VNC viewer? 3894 3895 Yes, a user mentions he uses the -gone option under CDE to run a 3896 screen lock program: 3897 x11vnc -display :0 -forever -gone 'dtaction LockDisplay' 3898 3899 Other possibilities are: 3900 x11vnc -display :0 -forever -gone 'xscreensaver-command -lock' 3901 x11vnc -display :0 -forever -gone 'kdesktop_lock' 3902 x11vnc -display :0 -forever -gone 'xlock &' 3903 x11vnc -display :0 -forever -gone 'xlock -mode blank &' 3904 3905 Here is a scheme using the -afteraccept option (in version 0.8) to 3906 unlock the screen after the first valid VNC login and to lock the 3907 screen after the last valid VNC login disconnects: 3908 x11vnc -display :0 -forever -shared -afteraccept ./myxlocker -gone ./myxlocke 3909 r 3910 3911 Where the script ./myxlocker is: 3912 #!/bin/sh 3913 3914 #/usr/bin/env | grep RFB_ | sort # for viewing RFB_* settings. 3915 3916 if [ "X$RFB_MODE" = "Xafteraccept" ]; then 3917 if [ "X$RFB_STATE" = "XNORMAL" ]; then # require valid login 3918 if [ "X$RFB_CLIENT_COUNT" = "X1" ]; then 3919 killall xlock # Linux only. 3920 fi 3921 fi 3922 elif [ "X$RFB_MODE" = "Xgone" ]; then 3923 if [ "X$RFB_STATE" = "XNORMAL" ]; then # require valid login 3924 if [ "X$RFB_CLIENT_COUNT" = "X0" ]; then 3925 xlock -mode blank & 3926 fi 3927 fi 3928 fi 3929 3930 Note the xlock option "-mode blank" to avoid animations. 3931 3932 There is a problem if you have x11vnc running this way in -forever 3933 mode and you hit Ctrl-C to stop it. The xlock (or other program) will 3934 get killed too. To work around this make a little script called 3935 setpgrp that looks like: 3936 #!/usr/bin/perl 3937 setpgrp(0, 0); 3938 exec @ARGV; 3939 3940 then use -gone "setpgrp xlock &", etc. 3941 [Encrypted Connections] 3942 3943 Q-50: How can I tunnel my connection to x11vnc via an encrypted SSH 3944 channel between two Unix machines? 3945 3946 See the description earlier on this page on how to tunnel VNC via SSH 3947 from Unix to Unix. A number of ways are described along with some 3948 issues you may encounter. 3949 3950 Other secure encrypted methods exists, e.g. stunnel, IPSEC, various 3951 VPNs, etc. 3952 3953 See also the Enhanced TightVNC Viewer (SSVNC) page where much of this 3954 is now automated. 3955 3956 3957 Q-51: How can I tunnel my connection to x11vnc via an encrypted SSH 3958 channel from Windows using an SSH client like Putty? 3959 3960 Above we described how to tunnel VNC via SSH from Unix to Unix, you 3961 may want to review it. To do this from Windows using Putty it would go 3962 something like this: 3963 * In the Putty dialog window under 'Session' enter the hostname or 3964 IP number of the Unix machine with display to be viewed. 3965 * Make sure the SSH protocol is selected and the server port is 3966 correct. 3967 * Under 'Connections/SSH/Tunnels' Add a Local connection with 3968 'Source port: 5900' and 'Destination: localhost:5900' 3969 * Log into the remote machine by pressing 'Open' and supplying 3970 username, password, etc. 3971 * In that SSH shell, start up x11vnc by typing the command: x11vnc 3972 -display :0 plus any other desired options (e.g. -localhost.) 3973 * Finally, start up your VNC Viewer in Windows and enter 3974 'localhost:0' as the VNC server. 3975 3976 You can keep all of the settings in a Putty 'Saved Session'. Also, 3977 once everything is working, you can consider putting x11vnc -display 3978 :0 (plus other cmdline options) in the 'Remote command' Putty setting 3979 under 'Connections/SSH'. 3980 3981 See also the Enhanced TightVNC Viewer (SSVNC) page where much of this 3982 is now automated via the Putty plink utility. 3983 3984 For extra protection feel free to run x11vnc with the -localhost and 3985 -rfbauth/-passwdfile options. 3986 3987 If the machine you SSH into via Putty is not the same machine with the 3988 X display you wish to view (e.g. your company provides incoming SSH 3989 access to a gateway machine), then you need to change the above Putty 3990 dialog setting to: 'Destination: otherhost:5900', Once logged in, 3991 you'll need to do a second login (ssh or rsh) to the workstation 3992 machine 'otherhost' and then start up x11vnc on it. This can also be 3993 automated by Chaining SSH's. 3994 3995 As discussed above another option is to first start the VNC viewer in 3996 "listen" mode, and then launch x11vnc with the "-connect localhost" 3997 option to establish the reverse connection. In this case a Remote port 3998 redirection (not Local) is needed for port 5500 instead of 5900 (i.e. 3999 'Source port: 5500' and 'Destination: localhost:5500' for a Remote 4000 connection.) 4001 4002 4003 Q-52: How can I tunnel my connection to x11vnc via an encrypted SSL 4004 channel using an external tool like stunnel? 4005 4006 It is possible to use a "lighter weight" encryption setup than SSH or 4007 IPSEC. SSL tunnels such as stunnel (also stunnel.org) provide an 4008 encrypted channel without the need for Unix users, passwords, and key 4009 passphrases required for ssh (and at the other extreme SSL can also 4010 provide a complete signed certificate chain of trust.) On the other 4011 hand, since SSH is usually installed everywhere and firewalls often 4012 let its port through, ssh is frequently the path of least resistance 4013 (it also nicely manages public keys for you.) 4014 4015 Update: As of Feb/2006 x11vnc has the options -ssl, -stunnel, and 4016 -sslverify to provide integrated SSL schemes. They are discussed in 4017 the Next FAQ (you probably want to skip to it now.) 4018 4019 We include these non-built-in method descriptions below for historical 4020 reference. They are handy because can be used to create SSL tunnels to 4021 any VNC (or other type of) server. 4022 4023 4024 Here are some basic examples using stunnel but the general idea for 4025 any SSL tunnel utility is the same: 4026 * Start up x11vnc and constrain it to listen on localhost. 4027 * Then start up the SSL tunnel running on the same machine to 4028 forward incoming connections to that x11vnc. 4029 * Set up and run a similar SSL tunnel for the outgoing connection on 4030 the VNC viewer machine pointing it to the SSL/x11vnc server. 4031 * Optionally, set up server (or even client) public/private keys for 4032 use in authenticating one side to the other. 4033 * Finally, start the VNC Viewer and tell it to connect to the local 4034 port (e.g. a vnc display localhost:0) where its outgoing SSL 4035 tunnel is listening. 4036 4037 We'll first use the stunnel version 3 syntax since it is the most 4038 concise and Unixy. 4039 4040 Start up x11vnc listening on port 5900: 4041 x11vnc -display :0 -rfbport 5900 -localhost -bg -passwdfile ~/mypass 4042 4043 Then start stunnel (version 3, not 4) with this command: 4044 stunnel -d 5901 -r 5900 -p /path/to/stunnel.pem 4045 4046 The above two commands are run on host "far-away.east". The 4047 stunnel.pem is the self-signed PEM file certificate created when 4048 stunnel is built. One can also create certificates signed by 4049 Certificate Authorities or self-signed if desired using the x11vnc 4050 utilities described there. 4051 4052 SSL Viewers: Next, on the VNC viewer side we need an SSL tunnel to 4053 encrypt the outgoing connection. The nice thing is any SSL tunnel can 4054 be used because the protocol is a standard. For this example we'll 4055 also use stunnel on the viewer side on Unix. First start up the 4056 client-side stunnel (version 3, not 4): 4057 stunnel -c -d localhost:5902 -r far-away.east:5901 4058 4059 Then point the viewer to the local tunnel on port 5902: 4060 vncviewer -encodings "copyrect tight zrle hextile" localhost:2 4061 4062 That's it. Note that the ss_vncviewer script can automate this 4063 easily, and so can the Enhanced TightVNC Viewer (SSVNC) package. 4064 4065 Be sure to use a VNC password because unlike ssh by default the 4066 encrypted SSL channel provides no authentication (only privacy.) With 4067 some extra configuration one could also set up certificates to provide 4068 authentication of either or both sides as well (and hence avoid 4069 man-in-the-middle attacks.) See the stunnel and openssl documentation 4070 and also the key management section for details. 4071 4072 stunnel has also been ported to Windows, and there are likely others 4073 to choose from for that OS. Much info for using it on Windows can be 4074 found at the stunnel site and in this article The article also shows 4075 the detailed steps to set up all the authentication certificates. (for 4076 both server and clients, see also the x11vnc utilities that do this.) 4077 The default Windows client setup (no certs) is simpler and only 4 4078 files are needed in a folder: stunnel.exe, stunnel.conf, libssl32.dll, 4079 libeay32.dll. We used an stunnel.conf containing: 4080 # stunnel.conf: 4081 client = yes 4082 options = ALL 4083 [myvncssl] 4084 accept = localhost:5902 4085 connect = far-away.east:5901 4086 4087 then double click on the stunnel.exe icon to launch it (followed by 4088 pointing the VNC viewer to localhost:2). 4089 4090 4091 stunnel inetd-like mode: 4092 4093 As an aside, if you don't like the little "gap" of unencrypted TCP 4094 traffic (and a localhost listening socket) on the local machine 4095 between stunnel and x11vnc it can actually be closed by having stunnel 4096 start up x11vnc in -inetd mode: 4097 stunnel -p /path/to/stunnel.pem -P none -d 5900 -l ./x11vnc_sh 4098 4099 Where the script x11vnc_sh starts up x11vnc: 4100 #!/bin/sh 4101 x11vnc -q -inetd -display :0 -passwdfile ~/mypass 4102 4103 Note that this creates a separate x11vnc process for each incoming 4104 connection (as any inetd x11vnc usage would), but for the case of 4105 normally just one viewer at a time it should not be a big problem. 4106 4107 4108 stunnel 4 syntax: 4109 4110 Somewhat sadly, the stunnel version 4 syntax is not so amenable to the 4111 command line or scripts. You need to create a config file with the 4112 parameters. E.g.: 4113 stunnel x11vnc.cfg 4114 4115 Where the file x11vnc.cfg contains: 4116 foreground = yes 4117 pid = 4118 cert = /path/to/stunnel.pem 4119 [x11vnc_stunnel] 4120 accept = 5901 4121 connect = 5900 4122 4123 One nice thing about version 4 is often the PEM file does not need to 4124 be specified because stunnel finds it in its installed area. One other 4125 gotcha the PEM file is usually only readable by root (it has the 4126 private key afterall), so you'll need to relax the permissions or make 4127 a copy that the user running x11vnc/stunnel can read. 4128 4129 4130 SSL VNC Viewers: 4131 4132 Regarding VNC viewers that "natively" do SSL unfortunately there do 4133 not seem to be many. The SingleClick UltraVNC Java Viewer is SSL and 4134 is compatible with x11vnc's -ssl option and stunnel.) Commercial 4135 versions of VNC seem to have some SSL-like encryption built in, but we 4136 haven't tried those either and they probably wouldn't work since their 4137 (proprietary) SSL-like negotiation is likely embedded in the VNC 4138 protocol unlike our case where it is external. 4139 4140 Note: as of Mar/2006 libvncserver/x11vnc provides a SSL-enabled Java 4141 applet that can be served up via the -httpdir or -http options when 4142 -ssl is enabled. It will also be served via HTTPS via either the VNC 4143 port (e.g. https://host:5900/) or a 2nd port via the -https option. 4144 4145 In general current SSL VNC solutions are not particularly "seemless". 4146 But it can be done, and with a wrapper script on the viewer side and 4147 the -stunnel or -ssl option on the server side it works well and is 4148 convenient. Here is a simple script ss_vncviewer that automates 4149 running stunnel on the VNC viewer side on Unix a little more carefully 4150 than the commands printed above. (One could probably do a similar 4151 thing with a .BAT file on Windows in the stunnel folder.) 4152 4153 Update Jul/2006: we now provide an Enhanced TightVNC Viewer (SSVNC) 4154 package that starts up STUNNEL automatically along with some other 4155 features. All binaries (stunnel, vncviewer, and some utilities) are 4156 provided in the package. It works on Unix, Mac OS X, and Windows. 4157 4158 4159 Q-53: Does x11vnc have built-in SSL tunneling? 4160 4161 You can read about non-built-in methods in the Previous FAQ for 4162 background. 4163 4164 SSL tunnels provide an encrypted channel without the need for Unix 4165 users, passwords, and key passphrases required for ssh (and at the 4166 other extreme SSL can also provide a complete signed certificate chain 4167 of trust.) On the other hand, since SSH is usually installed 4168 everywhere and firewalls often let its port through, ssh is frequently 4169 the path of least resistance. 4170 4171 Built-in SSL x11vnc options: 4172 4173 As of Feb/2006 the x11vnc -ssl option automates the SSL tunnel 4174 creation on the x11vnc server side. An SSL-enabled Java Viewer applet 4175 is also provided that can be served via HTTP or HTTPS to automate SSL 4176 on the client side. 4177 4178 The -ssl mode uses the www.openssl.org library if available at build 4179 time. 4180 4181 The mode requires an SSL certificate and key (i.e. .pem file.) These 4182 are usually created via the openssl(1) program (in fact in for "-ssl" 4183 (same as "-ssl SAVE") it will run openssl for you automatically.) So 4184 the SSL is not completely "built-in" since this external tool needs to 4185 be installed, but at least x11vnc runs it for you automatically. 4186 4187 An -ssl example: 4188 x11vnc -display :0 -ssl -passwdfile ~/mypass 4189 4190 You'll get output like this: 4191 09/04/2006 19:27:35 Creating a self-signed PEM certificate... 4192 09/04/2006 19:27:35 4193 ... 4194 4195 The SSL VNC desktop is: far-away.east:0 4196 PORT=5900 4197 SSLPORT=5900 4198 4199 In this case openssl(1) was used to create a PEM automatically. It 4200 will prompt you if you want to protect it with with a passphrase. Use 4201 "-ssl SAVE_NOPROMPT" to not be prompted. Use "-ssl TMP" to create a 4202 temporary self-signed cert that will be discarded when x11vnc exits. 4203 4204 Update: As of Nov/2008 x11vnc also supports the VeNCrypt SSL/TLS 4205 tunnel extension to the VNC protocol. The older ANONTLS method (vino) 4206 is also supported. This support is on by default when the -ssl option 4207 is in use and can be fine-tuned using these options: -vencrypt, 4208 -anontls, and -sslonly. 4209 4210 The normal x11vnc -ssl operation is somewhat like a URL method 4211 vncs://hostname if vnc://hostname indicates a standard unencrypted VNC 4212 connection. Just as https://hostname is an SSL encrypted version of 4213 http://hostname. The entire VNC session goes through the SSL tunnel. 4214 VeNCrypt, on the other hand, switches to SSL/TLS early in the VNC 4215 protocol handshake. x11vnc 0.9.6 supports both simultaneously when 4216 -ssl is active. 4217 4218 4219 SSL VNC Viewers:. Viewer-side will need to use SSL as well. See the 4220 next FAQ and here for SSL enabled VNC Viewers, including SSVNC, to 4221 connect to the above x11vnc via SSL. 4222 4223 4224 As seen above, the PEM (privacy enhanced mail) file does not need to 4225 be supplied if the openssl(1) command is available in PATH, in that 4226 case a self-signed, certificate good the current and subsequent x11vnc 4227 sessions is created (this may take a while on very slow machines.) 4228 4229 In general, the PEM file contains both the Certificate (i.e. public 4230 key) and the Private Key. Because of the latter, the file should be 4231 protected from being read by untrusted users. The best way to do this 4232 is to encrypt the key with a passphrase (note however this requires 4233 supplying the passphrase each time x11vnc is started up.) 4234 4235 See the discussion on x11vnc Key Management for some utilities 4236 provided for creating and managing certificates and keys and even for 4237 creating your own Certificate Authority (CA) for signing VNC server 4238 and client certificates. This may be done by importing the certificate 4239 into Web Browser or Java plugin keystores, or pointing stunnel to it. 4240 The wrapper script ss_vncviewer provides an example on unix (see the 4241 -verify option.) 4242 4243 Here are some notes on the simpler default (non-CA) operation. To have 4244 x11vnc save the generated certificate and key, use the "SAVE" keyword 4245 like this: 4246 x11vnc -ssl SAVE -display :0 ... 4247 4248 (this is the same as the default: "-ssl".) This way it will be saved 4249 in the default directory ~/.vnc/certs/ as server.crt (the certificate 4250 only) and server.pem (both certificate and private key.) This opens up 4251 the possibility of copying the server.crt to machines where the VNC 4252 Viewer will be run to enable authenticating the x11vnc SSL VNC server 4253 to the clients. When authentication takes place this way (or via the 4254 more sophisticated CA signing described here), then 4255 Man-In-The-Middle-Attacks are prevented. Otherwise, the SSL encryption 4256 only provides protection against passive network traffic "sniffing" 4257 (i.e. you are not protected against M-I-T-M attacks.) Nowadays, most 4258 people seem mostly concerned mainly about passive sniffing (and the 4259 default x11vnc SSL mode protects against it.) Note that there are 4260 hacker tools like dsniff/webmitm and cain that implement SSL 4261 Man-In-The-Middle attacks. They rely on the client not bothering to 4262 check the cert. 4263 4264 4265 One can test to some degree that SSL is working after starting x11vnc 4266 with the -stunnel or -ssl option. From another machine one can use the 4267 openssl command something like this: 4268 openssl s_client -debug -msg -showcerts -connect far-away.east:5900 4269 4270 After all of the debugging output and informational messages you'll 4271 see the string "RFB 003.008" that came from x11vnc. Pointing a web 4272 browser connecting to: https://far-away.east:5900/ and then viewing 4273 the SSL certificate information about the connection in the panels 4274 will also work. 4275 4276 Note: If you serve up the SSL enabled Java VNC Viewer via something 4277 like: 4278 x11vnc -ssl -httpdir /usr/local/share/x11vnc/classes/ssl 4279 4280 (or just the -http option), you can test it out completely using that, 4281 including using https to download it into the browser and connect to 4282 x11vnc. 4283 4284 4285 The older -stunnel option: Before the -ssl option there was a 4286 convenience option -stunnel that would start an external SSL tunnel 4287 for you using stunnel. The -ssl method is the preferred way, but for 4288 historical reference we keep the -stunnel info here. 4289 4290 The -stunnel mode requires the stunnel.mirt.net command stunnel(8) to 4291 be installed on the system. 4292 4293 Some -stunnel examples: 4294 x11vnc -display :0 -stunnel /path/to/stunnel.pem -passwdfile ~/mypass 4295 4296 x11vnc -display :0 -stunnel SAVE ... 4297 4298 You'll get output like this: 4299 The VNC desktop is: localhost:50 4300 The SSL VNC desktop is: far-away.east:0 4301 PORT=5950 4302 SSLPORT=5900 4303 4304 That indicates stunnel is listening on port 5900 for incoming 4305 SSL-wrapped VNC connections from viewers. x11vnc is listening for 4306 local connections on port 5950 in this case (remote viewers cannot 4307 connect to it directly.) For -stunnel to work the stunnel command must 4308 be installed on the machine and available in PATH (note stunnel is 4309 often installed in sbin directories rather than bin.) Note that the 4310 default "-stunnel" by itself creates a temporary cert (as in "-ssl 4311 TMP".) 4312 4313 4314 Q-54: How do I use VNC Viewers with built-in SSL tunneling? 4315 4316 Notes on using "native" VNC Viewers with SSL: 4317 4318 There aren't any native VNC Viewers that do SSL (ask your VNC viewer 4319 developer to add the feature.) So a tunnel must be setup that you 4320 point the VNC Viewer to. This is often STUNNEL. You can do this 4321 manually, or use the ss_vncviewer script on Unix, or our Enhanced 4322 TightVNC Viewer (SSVNC) package on Unix, Windows, or MacOSX. See the 4323 next section for Java Web browser SSL VNC Viewers (you only need a 4324 Java-enabled Web browser for it to work.) 4325 4326 Notes on the SSL enabled Java VNC Viewer provided in x11vnc 4327 classes/ssl/VncViewer.jar: 4328 4329 A Java applet VNC Viewer allows you to connect to a VNC Server from a 4330 Java-enabled Web browser. 4331 4332 The SSL enabled Java VNC Viewer (VncViewer.jar) in the x11vnc package 4333 supports only SSL based connections by default. As mentioned above the 4334 -httpdir can be used to specify the path to .../classes/ssl. A typical 4335 location might be /usr/local/share/x11vnc/classes/ssl. Or -http can be 4336 used to try to have it find the directory automatically. 4337 4338 Also note that the SingleClick UltraVNC Java Viewer is compatible with 4339 x11vnc's -ssl SSL mode. (We tested it this way: "java -cp 4340 ./VncViewer.jar VncViewer HOST far-away.east PORT 5900 USESSL 1 4341 TRUSTALL 1") 4342 4343 The Java viewer uses SSL to communicate securely with x11vnc. Note 4344 that the applet can optionally also be downloaded into your web 4345 browser via HTTPS (which is HTTP over SSL.) This way the HTML page and 4346 the Java applet itself are also delivered securely with SSL (as 4347 opposed to only the VNC traffic being encrypted with SSL.) 4348 4349 For this case the output will be something like this: 4350 x11vnc -ssl SAVE -http 4351 ... 4352 The SSL VNC desktop is: far-away.east:0 4353 Java SSL viewer URL: https://far-away.east:5900/ 4354 Java SSL viewer URL: http://far-away.east:5800/ 4355 PORT=5900 4356 SSLPORT=5900 4357 4358 Indicating the two URLs (the first one encrypted, the second not) one 4359 could point the web browser at to get the VNC viewer applet. E.g. put 4360 this 4361 http://far-away.east:5800/ 4362 4363 or: 4364 https://far-away.east:5900/ 4365 4366 into your Java-enabled Web browser. 4367 4368 Note that KDE's Konqueror web browser seems to have problems with 4369 https Java applets, so you'll have to use the http/5800 with it (if 4370 you get https/5900 working let us know how you did it.) 4371 4372 If you are using a router/firewall with port-redirection, and you are 4373 redirecting ports other than the default ones (5800, 5900) listed 4374 above see here. 4375 4376 The https service provided thru the actual VNC port (5900 in the above 4377 example) can occasionally be slow or unreliable (it has to read some 4378 input and try to guess if the connection is VNC or HTTP.) If it is 4379 unreliable for you and you still want to serve the Java applet via 4380 https, use the -https option to get an additional port dedicated to 4381 https (its URL will also be printed in the output.) 4382 4383 Another possibility is to add the GET applet parameter: 4384 https://far-away.east:5900/?GET=1 4385 4386 This will have the VNC Viewer send a special HTTP GET string "GET 4387 /request.https.vnc.connection HTTP/1.0" that x11vnc will notice more 4388 quickly as a request for a VNC connection. Otherwise it must wait for 4389 a timeout to expire before it assumes a VNC connection. 4390 4391 You may also use "urlPrefix=somestring" to have /somestring prepended 4392 to /request.https.vnc.connection". Perhaps you are using a web server 4393 proxy scheme to enter a firewall or otherwise have rules applied to 4394 the URL. If you need to have any slashes "/" in "somestring" use 4395 "_2F_" (a deficiency in libvncserver prevents using the more natural 4396 "%2F".) 4397 4398 You apply multiple applet parameters in the regular URL way, e.g.: 4399 https://far-away.east:5900/?GET=1&urlPrefix=mysubdir&... 4400 4401 All of the x11vnc Java Viewer applet parameters are described in the 4402 file classes/ssl/README 4403 4404 4405 Tips on Getting the SSL Java Applet Working the First Time: 4406 Unfortunately, it can be a little tricky getting the SSL VNC Java 4407 Viewer working with x11vnc. Here are some tips to getting working the 4408 first time (afterwards you can incrementally customize with more 4409 complex settings.) 4410 * First try it on the LAN: Do NOT try to have it work the first time 4411 going through firewalls, Web proxies, home router port 4412 redirections, or Apache portal. Just try a direct connection over 4413 your LAN first (if you only have 1 machine and no LAN, just do a 4414 direct connection to the same machine: localhost.) If the LAN 4415 machine you run x11vnc on has its own host-level firewall (most 4416 linux machine come with that on by default), disable it or at 4417 least let tcp ports 5800-6000 through. 4418 * First try HTTP to download the Java Applet: x11vnc can serve both 4419 the Java Applet jar file and VNC out of the same port (both 4420 tunneled through SSL, see below.) But it can lead to timing and 4421 other problems. So first try HTTP instead of HTTPS to download the 4422 Applet jar file (VncViewer.jar.) That is to say try 4423 http://hostname:5800 in your web browser first before trying 4424 https://hostname:5900. x11vnc will print out the ports and URLs it 4425 is using, so use the HTTP one it prints out. 4426 * Always Restart the Browser: If you are having failures and have to 4427 repeatedly retry things ALWAYS restart the browser (i.e. 4428 completely exit it and then start a new browser process) each 4429 time. Otherwise as you are changing things the browser may 4430 "remember" failed applet downloads, etc. and just add to the 4431 confusion and irreproducibility. If you see it trying to download 4432 VncViewer.class (instead of VncViewer.jar) you know it is really 4433 confused and needs to be restarted. 4434 * Step Lively: If you get Browser or Java VM or VNC Viewer applet 4435 dialog boxes saying things like "Do you want to trust this 4436 certificate?" or "The hostname does not match the one on the 4437 certificate", etc. just go through them as quickly as possible. 4438 x11vnc cannot wait forever for each SSL connection, and so if you 4439 dawdle too long inspecting the certs, etc it can lead to problems. 4440 Get it working first before taking your time to read the details 4441 in the dialogs, etc. 4442 * No inetd, Please: Even if you intend to deploy via inetd or xinetd 4443 eventually, get that working later (and remember do not use 4444 something like "-ssl TMP" that creates a new temporary SSL 4445 certificate for every new socket connection.) 4446 * Nothing Fancy: Do not try fancy stuff like -svc, -create, -unixpw, 4447 "-users unixpw=", "-users sslpeer=", -sslverify, etc. Just get the 4448 simplest connection working first and then incrementally add what 4449 you need. 4450 4451 So the recommended test command lines are: 4452 x11vnc -ssl SAVE -http 4453 x11vnc -ssl SAVE -httpdir /path/to/x11vnc/classes/ssl 4454 4455 Use the latter if x11vnc cannot automatically find the classes/ssl 4456 directory (this what the -http option instructs it to do.) Then point 4457 your browser to the HTTP (not HTTPS) URL it prints out. 4458 4459 Following the above guidelines, did it work? If so, Congratulations!! 4460 you created an SSL encrypted connection between the SSL Java applet 4461 running in your web browser and x11vnc. The fact that you used HTTP 4462 instead of HTTPS to download the applet is not the end of the world 4463 (some users do it this way), the main thing is that the VNC traffic is 4464 encrypted with SSL. If you are having trouble even with the above 4465 baseline test case feel free to contact me (please send the Full 4466 x11vnc output, not just part of it; the complete x11vnc command line; 4467 the URL(s) entered in the browser; the full Java Console output; and 4468 anything else you can think of.) 4469 4470 Next, you can add the features you want one by one testing it still 4471 works each time. I suggest first turning on the HTTPS applet download 4472 (https://hostname:5900) if that is what you intend to use. That one 4473 gives the most trouble because of the ambiguity of passing two 4474 different protocols (HTTP and VNC) through the same SSL service port. 4475 4476 Next, turn on inetd if you intend to use that (this can be tricky too, 4477 be sure to use -oa logfile and inspect it carefully if there are 4478 problems.) If you are going to use non-standard ports (e.g. "-rfbport 4479 443" as root), work on that next. Then enable the firewall, router 4480 port redirection channel (you will somehow need to be outside to do 4481 that, maybe test that through another VNC session.) 4482 4483 Then, if you plan to use them, enable "fancy stuff" like "-svc" or 4484 "-unixpw", etc, etc. Be sure to add a password either "-rfbauth" or 4485 "-unixpw" or both. If you need to have the web browser use a corporate 4486 Web Proxy (i.e. it cannot connect directly) work on that last. Ditto 4487 for the Apache portal. 4488 4489 4490 Router/Firewall port redirs: If you are doing port redirection at 4491 your router to an internal machine running x11vnc AND the internet 4492 facing port is different from the internal machine's VNC port, you 4493 will need to apply the PORT applet parameter to indicate to the applet 4494 the Internet facing port number (otherwise by default the internal 4495 machine's port, say 5900, is sent and that of course is rejected at 4496 the firewall/router.) For example: 4497 https://far-away.east:443/?GET=1&PORT=443 4498 4499 So in this example the user configures his router to redirect 4500 connections to port 443 on his Internet side to, say, port 5900 on the 4501 internal machine running x11vnc. See also the -httpsredir option that 4502 will try to automate this for you. 4503 4504 To configure your router to do port redirection, see its instructions. 4505 Typically, from the inside you point a web browser to a special URL 4506 (e.g. http://192.168.1.1) and you get a web interface to configure it. 4507 Look for something like "Port Redirection" or "Port Forwarding", 4508 probably under "Advanced" or something like that. If you have a Linux 4509 or Unix system acting as your firewall/router, see its firewall 4510 configuration. 4511 4512 You can also use x11vnc options -rfbport NNNNN and -httpport NNNNN to 4513 match the ports that your firewall will be redirecting to the machine 4514 where x11vnc is run. 4515 4516 4517 Tedious Dialogs: If you do serve the SSL enabled Java viewer via https 4518 be prepared for quite a number of "are you sure you trust this site?" 4519 dialogs: 4520 * First from the Web browser that cannot verify the self-signed 4521 certificate when it downloads index.vnc. 4522 * From the Web browser again noting that the common name on the 4523 certificate does not match the hostname of the remote machine. 4524 * Next from the Java VM that cannot verify the self-signed 4525 certificate when it downloads VncViewer.jar. 4526 * And also from the Java VM again noting that the common name on the 4527 certificate does not match the hostname of the remote machine. 4528 * Finally from the Java VncViewer applet itself saying it cannot 4529 verify the certificate! (or a popup asking you if you want to see 4530 the certificate.) 4531 4532 Note that sometimes if you pause too long at one of the above dialogs 4533 then x11vnc may exceed a timeout and assume the current socket 4534 connection is VNC instead of the HTTPS it actually is (but since you 4535 have paused too long at the dialog the GET request comes too late.) 4536 Often hitting Reload and going through the dialogs more quickly will 4537 let you connect. The Java VM dialogs are the most important ones to 4538 NOT linger at. If you see in the x11vnc output a request for 4539 VncViewer.class instead of VncViewer.jar it is too late... you will 4540 need to completely restart the Web browser to get it to try for the 4541 jar again. You can use the -https option if you want a dedicated port 4542 for HTTPS connections instead of sharing the VNC port. 4543 4544 To see example x11vnc output for a successful https://host:5900/ 4545 connection with the Java Applet see This Page. And here is a newer 4546 example including the Java Console output. 4547 4548 All of the x11vnc Java Viewer applet parameters are described in the 4549 file classes/ssl/README 4550 4551 4552 Notes on the VNC Viewer ss_vncviewer wrapper script: 4553 4554 If you want to use a native VNC Viewer with the SSL enabled x11vnc you 4555 will need to run an external SSL tunnel on the Viewer side. There do 4556 not seem to be any native SSL VNC Viewers outside of our x11vnc and 4557 SSVNC packages. The basic ideas of doing this were discussed for 4558 external tunnel utilities here. 4559 4560 The ss_vncviewer script provided with x11vnc and SSVNC can set up the 4561 stunnel tunnel automatically on unix as long as the stunnel command is 4562 installed on the Viewer machine and available in PATH (and vncviewer 4563 too of course.) Note that on a Debian based system you will need to 4564 install the package stunnel4 not stunnel. You can set the environment 4565 variables STUNNEL and VNCVIEWERCMD to point to the correct programs if 4566 you want to override the defaults. 4567 4568 Here are some examples: 4569 1) ss_vncviewer far-away.east:0 4570 4571 2) ss_vncviewer far-away.east:0 -encodings "copyrect tight zrle hextile" 4572 4573 3) ss_vncviewer -verify ./server.crt far-away.east:0 4574 4575 4) ss_vncviewer -mycert ./client.pem far-away.east:0 4576 4577 5) ss_vncviewer -proxy far-away.east:8080 myworkstation:0 4578 4579 The first one is the default mode and accepts the x11vnc certificate 4580 without question. The second one is as the first, but adds the 4581 -encodings options to the vncviewer command line. 4582 4583 The third one requires that the x11vnc server authenticate itself to 4584 the client against the certificate in the file ./server.crt (e.g. one 4585 created by "x11vnc -ssl SAVE" and safely copied to the VNC viewer 4586 machine.) 4587 4588 The fourth one is for VNC Viewer authentication, it uses ./client.pem 4589 to authenticate itself to x11vnc. One can supply both -verify and 4590 -mycert simultaneously. 4591 4592 The fifth one shows that Web proxies can be used if that is the only 4593 way to get out of the firewall. If the "double proxy" situation arises 4594 separate the two by commas. See this page for more information on how 4595 Web proxies come into play. 4596 4597 If one uses a Certificate Authority (CA) scheme described here, the 4598 wrapper script would use the CA cert instead of the server cert: 4599 3') ss_vncviewer -verify ./cacert.crt far-away.east:0 4600 4601 Update Jul/2006: we now provide an Enhanced TightVNC Viewer (SSVNC) 4602 package that starts up STUNNEL automatically along with some other 4603 features. All binaries (stunnel, vncviewer, and some utilities) are 4604 provided in the package. It works on Unix, Mac OS X, and Windows. 4605 4606 4607 Q-55: How do I use the Java applet VNC Viewer with built-in SSL 4608 tunneling when going through a Web Proxy? 4609 The SSL enabled Java VNC Viewer and firewall Proxies: 4610 4611 SSL and HTTPS aside, there is a general problem with Firewall Proxies 4612 and Java Applets that open sockets. The applet is downloaded 4613 successfully (through the browser) using HTTP and the proxy, but when 4614 the applet tries to reconnect to the originating host (the only one 4615 allowed by security) it does not use the proxy channel. So it cannot 4616 reconnect to the server the applet came from! 4617 4618 We have found a convenient workaround: in the directory where 4619 VncViewer.jar resides there is a digitally signed version of the same 4620 applet called SignedVncViewer.jar. Since the applet is digitally 4621 signed, there will be an additional dialog from the Java VM plugin 4622 asking you if you want to trust the applet fully. 4623 4624 You should say "Yes". If you do, the applet will be run in a mode 4625 where it can try to determine the firewall proxy host name and port 4626 (it will ask you for them if it cannot find them.) This way it can 4627 connect directly to the Proxy and then request the CONNECT method to 4628 be redirected to the originating host (the x11vnc VNC Server.) SSL is 4629 then layered over this socket. 4630 4631 To do this you should use the proxy.vnc HTML file like via this URL in 4632 your browser: 4633 https://yourmachine.com:5900/proxy.vnc 4634 4635 (instead of the unsigned one in https://yourmachine.com:5900/ that 4636 gives the default index.vnc) 4637 4638 Proxies that limit CONNECT to ports 443 and 563: 4639 4640 Things become trickier if the Web proxy restricts which CONNECT ports 4641 can be redirected to. For security, some (most?) proxies only allow 4642 port 443 (HTTPS) and 563 (SNEWS) by default. In this case, the only 4643 thing to do is run x11vnc on that low port, e.g. "-rfbport 443", (or 4644 use a port redirection on, say, a firewall or router port 443 to the 4645 internal machine.) 4646 4647 If you do such a redirection to an internal machine and x11vnc is not 4648 listening on port 443, you will probably need to edit proxy.vnc. 4649 Suppose the SSL x11vnc server was listening on port 5901. You should 4650 change the line in proxy.vnc from: 4651 <param name=PORT value=$PORT> 4652 4653 to: 4654 <param name=PORT value=443> 4655 4656 Since otherwise $PORT will be expanded to 5901 by x11vnc and the 4657 viewer applet will fail to connect to that port on the firewall. 4658 4659 Another way to achieve the same thing is to use the applet PORT 4660 parameter: 4661 https://yourmachine.com/proxy.vnc?PORT=443 4662 4663 this is cleaner because it avoids editing the file, but requires more 4664 parameters in the URL. See also the -httpsredir x11vnc option that 4665 will try to automate this for you. To use the GET trick discussed 4666 above, do: 4667 https://yourmachine.com/proxy.vnc?GET=1&PORT=443 4668 4669 All of the x11vnc Java Viewer applet parameters are described in the 4670 file classes/ssl/README 4671 4672 Here is an example of Java Console and x11vnc output for the Web proxy 4673 case. 4674 4675 4676 Note that both the ss_vncviewer stunnel Unix wrapper script and 4677 Enhanced TightVNC Viewer (SSVNC) can use Web proxies as well even 4678 though they do not involve a Web browser. 4679 4680 4681 Q-56: Can Apache web server act as a gateway for users to connect via 4682 SSL from the Internet with a Web browser to x11vnc running on their 4683 workstations behind a firewall? 4684 Yes. You will need to configure apache to forward these connections. 4685 It is discussed here. This SSL VNC portal provides a clean alternative 4686 to the traditional method where the user uses SSH to log in through 4687 the gateway to create the encrypted port redirection to x11vnc running 4688 on her desktop. 4689 4690 Also see the desktop.cgi CGI script method that achieves much of what 4691 this Apache VNC SSL portal method does (as long as desktop.cgi's 'port 4692 redirection' mode is enabled.) 4693 4694 4695 Q-57: Can I create and use my own SSL Certificate Authority (CA) with 4696 x11vnc? 4697 Yes, see this page for how to do this and the utility commands x11vnc 4698 provides to create and manage many types of certificates and private 4699 keys. 4700 4701 4702 4703 [Display Managers and Services] 4704 4705 Q-58: How can I run x11vnc as a "service" that is always available? 4706 4707 There are a number of ways to do this. The primary thing you need to 4708 decide is whether you want x11vnc to connect to the X session on the 4709 machine 1) regardless of who (or if anyone) has the X session, or 2) 4710 only if a certain user has the X session. Because X sessions are 4711 protected by X permissions (MIT-MAGIC-COOKIE files XAUTHORITY and 4712 $HOME/.Xauthority) the automatically started x11vnc will of course 4713 need to have sufficient permissions to connect to the X display. 4714 4715 Here are some ideas: 4716 * Use the description under "Continuously" in the FAQ on x11vnc and 4717 Display Managers 4718 * Use the description in the FAQ on x11vnc and inetd(8) 4719 * Use the description in the FAQ on Unix user logins and inetd(8) 4720 * Start x11vnc from your $HOME/.xsession (or $HOME/.xinitrc or 4721 autostart script or ...) 4722 * Although less reliable, see the x11vnc_loop rc.local hack below. 4723 4724 The display manager scheme will not be specific to which user has the 4725 X session unless a test is specifically put into the display startup 4726 script (often named Xsetup.) The inetd(8) scheme may or may not be 4727 specific to which user has the X session (and it may not be able to do 4728 all users via the XAUTHORITY permission issues.) 4729 4730 The .xsession/.xinitrc scheme is obviously is specific to a particular 4731 user and only when they are logged into X. If you do not know what a 4732 $HOME/.xsession script is or how to use one, perhaps your desktop has 4733 a "session startup commands" configuration option. The command to be 4734 run in the .xsession or .xinitrc file may look like this: 4735 x11vnc -logfile $HOME/.x11vnc.log -rfbauth $HOME/.vnc/passwd -forever -bg 4736 4737 plus any other options you desire. 4738 4739 Depending on your desktop and/or OS/distribution the automatically run 4740 X startup scripts (traditionally .xsession/.xinitrc) may have to be in 4741 a different directory or have a different basename. One user 4742 recommends the description under 'Running Scripts Automatically' at 4743 this link. 4744 4745 Firewalls: note all methods will require the host-level firewall to be 4746 configured to allow connections in on a port. E.g. 5900 (default VNC 4747 port) or 22 (default SSH port for tunnelling VNC.) Most systems these 4748 days have firewalls turned on by default, so you will actively have to 4749 do something to poke a hole in the firewall at the desired port 4750 number. See your system administration tool for Firewall settings 4751 (Yast, Firestarter, etc.) 4752 4753 4754 Q-59: How can I use x11vnc to connect to an X login screen like xdm, 4755 GNOME gdm, KDE kdm, or CDE dtlogin? (i.e. nobody is logged into an X 4756 session yet.) 4757 4758 We describe two scenarios here. The first is called 'One time only' 4759 meaning you just need to do it quickly once and don't want to repeat; 4760 and the second is called 'Continuously' meaning you want the access to 4761 be available after every reboot and after every desktop logout. 4762 _________________________________________________________________ 4763 4764 One time only: If the X login screen is running and you just want to 4765 connect to it once (i.e. a one-shot): 4766 4767 It is usually possible to do this by just adjusting the XAUTHORITY 4768 environment variable to point to the correct MIT-COOKIE auth file 4769 while running x11vnc as root, e.g. for the gnome display manager, GDM: 4770 x11vnc -auth /var/gdm/:0.Xauth -display :0 4771 4772 (the -auth option sets the XAUTHORITY variable for you.) 4773 4774 There will be a similar thing to do for xdm using however a different 4775 auth directory path (perhaps something like 4776 /var/lib/xdm/authdir/authfiles/A:0-XQvaJk) for the xdm greeter or 4777 /var/lib/kdm/A:0-crWk72 (or /var/run/xauth/A:0-qQPftr, etc. etc) for 4778 the kdm greeter. Of course, the random characters in the file basename 4779 will vary and you will need to use the actual filename on your system. 4780 Read your system docs to find out where the display manager cookie 4781 files are kept. 4782 4783 Trick: sometimes ps(1) can reveal the X server process -auth argument 4784 (e.g. "ps wwaux | grep auth") and hence the path to the auth file. 4785 4786 x11vnc must be run as root for this because the /var/gdm/:0.Xauth, 4787 /var/lib/kdm/A:0-crWk72, etc. auth files are only readable by root. If 4788 you do not want to run x11vnc as root, you can copy (as root or sudo) 4789 the auth file to some location and make it readable by your userid. 4790 Then run x11vnc as your userid with -auth pointed to the copied file. 4791 4792 Update Dec/2009: use "-auth guess" to have x11vnc try to guess the 4793 location of the auth file for you. 4794 4795 You next connect to x11vnc with a VNC viewer, give your username and 4796 password to the X login prompt to start your session. 4797 4798 Note: GDM: gdm seems to have an annoying setting that causes x11vnc 4799 (and any other X clients) to be killed after the user logs in. Setting 4800 KillInitClients=false in the [daemon] section of /etc/X11/gdm/gdm.conf 4801 (or /etc/gdm/gdm.conf, etc.) avoids this. Otherwise, just restart 4802 x11vnc and then reconnect your viewer. Other display managers (kdm, 4803 etc) may also have a similar problem. One user reports having to alter 4804 "gdm.conf-custom" as well. 4805 4806 Note: Solaris: For dtlogin in addition to the above sort of trick 4807 (BTW, the auth file should be in /var/dt), you'll also need to add 4808 something like Dtlogin*grabServer:False to the Xconfig file 4809 (/etc/dt/config/Xconfig or /usr/dt/config/Xconfig on Solaris, see the 4810 example at the end of this FAQ.) Then restart dtlogin, e.g.: 4811 /etc/init.d/dtlogin stop; /etc/init.d/dtlogin start or reboot. 4812 4813 Update Nov/2008: Regarding GDM KillInitClients: see the -reopen option 4814 for another possible workaround. 4815 4816 Update Oct/2009: Regarding GDM KillInitClients: starting with x11vnc 4817 0.9.9 it will try to apply heuristics to detect if a window manager is 4818 not running (i.e. whether the Display Manager Greeter Login panel is 4819 still up.) If it thinks the display manager login is still up it will 4820 delay creating windows or using XFIXES. The former is what GDM uses to 4821 kill the initial clients, use of the latter can cause a different 4822 problem: an Xorg server crash. So with 0.9.9 and later it should all 4823 work without needing to set KillInitClients=false (which is a good 4824 because recent GDM, v2.24, has removed this option) or use -noxfixes. 4825 To disable the heuristics and delaying set X11VNC_AVOID_WINDOWS=never; 4826 to set the delay time explicitly use, e.g., X11VNC_AVOID_WINDOWS=120 4827 (delays for 120 seconds after the VNC connection; you have that long 4828 to log in.) 4829 _________________________________________________________________ 4830 4831 Continuously: Have x11vnc reattach each time the X server is 4832 restarted (i.e. after each logout and reboot): 4833 4834 To make x11vnc always attached to the X server including the login 4835 screen you will need to add a command to a display manager startup 4836 script. 4837 4838 Please consider the security implications of this! The VNC display for 4839 the X session always accessible (but hopefully password protected.) 4840 Add -localhost if you only plan to access via a SSH tunnel. 4841 4842 The name of the display manager startup script file depends on desktop 4843 used and seem to be: 4844 GDM (GNOME) /etc/X11/gdm/Init/Default 4845 /etc/gdm/Init/Default 4846 KDM (KDE) /etc/kde*/kdm/Xsetup 4847 XDM /etc/X11/xdm/Xsetup (or sometimes xdm/Xsetup_0) 4848 CDE /etc/dt/config/Xsetup 4849 4850 although the exact location can be operating system, distribution, and 4851 time dependent. See the documentation for your display manager: 4852 gdm(1), kdm(1), xdm(1), dtlogin(1) for additional details. There may 4853 also be display number specific scripts: e.g. Xsetup_0 vs. Xsetup, you 4854 need to watch out for. 4855 4856 Note: You should read and understand all of the Note's and Update's 4857 in the 'One time only' section above. All of the GDM topics apply here 4858 as well: 4859 4860 Note: GDM: The above (in 'One time only') gdm setting of 4861 KillInitClients=false in /etc/X11/gdm/gdm.conf (or /etc/gdm/gdm.conf, 4862 etc.) for GDM is needed here as well. Other display managers (KDM, 4863 etc) may also have a similar problem. 4864 4865 Also see the Update Oct/2009 above where x11vnc 0.9.9 and later 4866 automatically avoids being killed. 4867 4868 Note: DtLogin: The above (in 'One time only') 4869 Dtlogin*grabServer:False step for Solaris will be needed for dtlogin 4870 here as well. 4871 4872 In any event, the line you will add to the display manager script 4873 (Xsetup, Default, or whatever) will look something like: 4874 /usr/local/bin/x11vnc -rfbauth /path/to/the/vnc/passwd -o /var/log/x11vnc.log 4875 -forever -bg 4876 4877 where you should customize the exact command to your needs (e.g. 4878 -localhost for SSH tunnel-only access; -ssl SAVE for SSL access; etc.) 4879 4880 Happy, happy, joy, joy: Note that we do not need to specify -display 4881 or -auth because happily they are already set for us in the DISPLAY 4882 and XAUTHORITY environment variables for the Xsetup script!!! 4883 4884 You may also want to force the VNC port with something like "-rfbport 4885 5900" (or -N) to avoid autoselecting one if 5900 is already taken. 4886 _________________________________________________________________ 4887 4888 Fedora/gdm: Here is an example of what we did on a vanilla install of 4889 Fedora-C3 (seems to use gdm by default.) Add a line like this to 4890 /etc/X11/gdm/Init/:0 4891 /usr/local/bin/x11vnc -rfbauth /etc/x11vnc.passwd -forever -bg -o /var/log/x1 4892 1vnc.log 4893 4894 And then add this line to /etc/X11/gdm/gdm.conf (or /etc/gdm/gdm.conf, 4895 etc.) in the [daemon] section: 4896 KillInitClients=false 4897 4898 Then restart: /usr/sbin/gdm-restart (or reboot.) The 4899 KillInitClients=false setting is important: without it x11vnc will be 4900 killed immediately after the user logs in. Here are full details on 4901 how to configure gdm 4902 _________________________________________________________________ 4903 4904 Solaris/dtlogin: Here is an example of what we did on a vanilla 4905 install of Solaris: 4906 Make the directory /etc/dt/config: 4907 mkdir -p /etc/dt/config 4908 4909 Copy over the Xconfig file for customization: 4910 cp /usr/dt/config/Xconfig /etc/dt/config/Xconfig 4911 4912 Edit /etc/dt/config/Xconfig and uncomment the line: 4913 Dtlogin*grabServer: False 4914 4915 Next, copy over Xsetup for customization: 4916 cp /usr/dt/config/Xsetup /etc/dt/config/Xsetup 4917 4918 Edit /etc/dt/config/Xsetup and at the bottom put a line like: 4919 /usr/local/bin/x11vnc -forever -o /var/log/x11vnc.log -bg 4920 4921 (tweaked to your local setup and preferences, a password via -rfbauth, 4922 etc. would be a very good idea.) 4923 4924 Restart the X server and dtlogin: 4925 /etc/init.d/dtlogin stop 4926 /etc/init.d/dtlogin start 4927 4928 (or reboot or maybe just restart the X session.) 4929 _________________________________________________________________ 4930 4931 KDM: One user running the kdm display manager reports putting this 4932 line: 4933 x11vnc -forever -rfbauth /home/xyz/.vnc/passwd -bg -o /var/log/x11vnc.log 4934 4935 in /etc/kde/kdm/Xsetup. After rebooting the system it all seemed to 4936 work fine. 4937 _________________________________________________________________ 4938 4939 4940 If you do not want to deal with any display manager startup scripts, 4941 here is a kludgey script that can be run manually or out of a boot 4942 file like rc.local: x11vnc_loop It will need some local customization 4943 before running. Because the XAUTHORITY auth file must be guessed by 4944 this script, use of the display manager script method described above 4945 is greatly preferred. There is also the -loop option that does 4946 something similar. 4947 4948 If the machine is a traditional Xterminal you may want to read this 4949 FAQ. 4950 4951 Firewalls: note all methods will require the host-level firewall to be 4952 configured to allow connections in on a port. E.g. 5900 (default VNC 4953 port) or 22 (default SSH port for tunnelling VNC.) Most systems these 4954 days have firewalls turned on by default, so you will actively have to 4955 do something to poke a hole in the firewall at the desired port 4956 number. See your system administration tool for Firewall settings 4957 (Yast, Firestarter, etc.) 4958 4959 4960 Q-60: Can I run x11vnc out of inetd(8)? How about xinetd(8)? 4961 4962 Yes, perhaps a line something like this in /etc/inetd.conf will do it 4963 for you: 4964 4965 5900 stream tcp nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc_sh 4966 4967 where the shell script /usr/local/bin/x11vnc_sh uses the -inetd option 4968 and looks something like (you'll need to customize to your settings.) 4969 #!/bin/sh 4970 /usr/local/bin/x11vnc -inetd -display :0 -auth /home/fred/.Xauthority \ 4971 -rfbauth /home/fred/.vnc/passwd -o /var/log/x11vnc_sh.log 4972 4973 Important: Note that you must redirect the standard error output to a 4974 log file (e.g. -o logfile) or "2>/dev/null" for proper operation via 4975 inetd (otherwise the standard error also goes to the VNC vncviewer, 4976 and that confuses it greatly, causing it to abort.) If you do not use 4977 a wrapper script as above but rather call x11vnc directly in 4978 /etc/inetd.conf and do not redirect stderr to a file, then you must 4979 specify the -q (aka -quiet) option: "/usr/local/bin/x11vnc -q -inetd 4980 ...". When you supply both -q and -inet and no "-o logfile" then 4981 stderr will automatically be closed (to prevent, e.g. library stderr 4982 messages leaking out to the viewer.) The recommended practice is to 4983 use "-o logfile" to collect the output in a file or wrapper script 4984 with "2>logfile" redirection because the errors and warnings printed 4985 out are very useful in troubleshooting problems. 4986 4987 Note also the need to set XAUTHORITY via -auth to point to the 4988 MIT-COOKIE auth file to get permission to connect to the X display 4989 (setting and exporting the XAUTHORITY variable accomplishes the same 4990 thing.) See the x11vnc_loop file in the previous question for more 4991 ideas on what that auth file may be, etc. The scheme described in the 4992 FAQ on Unix user logins and inetd(8) works around the XAUTHORITY issue 4993 nicely. 4994 4995 Note: On Solaris you cannot have the bare number 5900 in 4996 /etc/inetd.conf, you'll need to replace it with a word like x11vnc an 4997 then put something like "x11vnc 5900/tcp" in /etc/services. 4998 4999 Since the process runs as root, it might be a bad idea to have the 5000 logfile in a world-writable area like /tmp if there are untrustworthy 5001 users on the machine. Perhaps /var/log is a better place. 5002 5003 Be sure to look at your /etc/hosts.allow and /etc/hosts.deny settings 5004 to limit the machines that can connect to this service (your desktop!) 5005 For the above example with /etc/hosts.allow: 5006 x11vnc_sh : 123.45.67.89 5007 5008 A really safe way to do things is to limit the above inetd to 5009 localhost only (via /etc/hosts.allow) and use ssh to tunnel the 5010 incoming connection. Using inetd for this prevents there being a tiny 5011 window of opportunity between x11vnc starting up and your vncviewer 5012 connecting to it. Always use a VNC password to further protect against 5013 unwanted access. 5014 5015 For xinetd(8), one user reports he created the file 5016 /etc/xinetd.d/x11vncservice containing the following: 5017 # default: off 5018 # description: 5019 service x11vncservice 5020 { 5021 flags = REUSE NAMEINARGS 5022 port = 5900 5023 type = UNLISTED 5024 socket_type = stream 5025 protocol = tcp 5026 wait = no 5027 user = root 5028 server = /usr/sbin/tcpd 5029 server_args = /usr/local/bin/x11vnc_sh 5030 disable = no 5031 } 5032 5033 With the contents of /usr/local/bin/x11vnc_sh similar to the example 5034 given above. One user reports this works with avoiding the wrapper 5035 script: 5036 service x11vncservice 5037 { 5038 port = 5900 5039 type = UNLISTED 5040 socket_type = stream 5041 protocol = tcp 5042 wait = no 5043 user = root 5044 server = /usr/local/bin/x11vnc 5045 server_args = -inetd -q -display :0 -auth /var/gdm/:0.Xauth 5046 disable = no 5047 } 5048 5049 (or one can replace the -q with say "-o /var/log/x11vnc.log" to 5050 capture a log) 5051 5052 The above works nicely for GDM because the -auth file is a fixed name. 5053 For KDM or XDM the filename varies. Here is one idea for a x11vnc_sh 5054 wrapper to try to guess the name: 5055 #!/bin/sh 5056 COLUMNS=256 5057 export COLUMNS 5058 authfile=`ps wwaux | grep '/X.*-auth' | grep -v grep | sed -e 's/^.*-auth *//' 5059 -e 's/ .*$//' | head -n 1` 5060 5061 if [ -r "$authfile" ]; then 5062 exec /usr/local/bin/x11vnc -inetd -o /var/log/x11vnc.log -display :0 -a 5063 uth "$authfile" 5064 fi 5065 exit 1 5066 5067 Starting with x11vnc 0.9.3 this can be automated by: 5068 #!/bin/sh 5069 exec /usr/local/bin/x11vnc -inetd -o /var/log/x11vnc.log -find -env FD_XDM=1 5070 5071 5072 Q-61: Can I have x11vnc advertise its VNC service and port via mDNS / 5073 Zeroconf (e.g. Avahi) so VNC viewers on the local network can detect 5074 it automatically? 5075 5076 Yes, as of Feb/2007 x11vnc supports mDNS / Zeroconf advertising of its 5077 service via the Avahi client library. Use the option -avahi (same as 5078 -mdns or -zeroconf) to enable it. Depending on your setup you may need 5079 to install Avahi (including the development/build packages), enable 5080 the server: avahi-daemon and avahi-dnsconfd, and possibly open up UDP 5081 port 5353 on your firewall. 5082 5083 If the Avahi client library or build environment is not available at 5084 build-time, then at run-time x11vnc will try to look for external 5085 helper programs, avahi-browse(1) or dns-sd(1), to do the work. 5086 5087 The service was tested with Chicken of the VNC ("Use Bonjour" 5088 selected) on a Mac on the same network and the service was noted and 5089 listed in the servers list. Clicking on it and then "Connect" 5090 connected automatically w/o having to enter any hostnames or port 5091 numbers. 5092 5093 It appears SuSE 10.1 comes with avahi (or you can add packages, e.g. 5094 avahi-0.6.5-27) but not the development package (you can use the 5095 OpenSuSE avahi-devel rpm.) Unfortunately, you may need to disable 5096 another Zeroconf daemon "/etc/init.d/mdnsd stop", before doing 5097 "/etc/init.d/avahi-daemon start" and "/etc/init.d/avahi-dnsconfd 5098 start". We also had to comment out the browse-domains line in 5099 /etc/avahi/avahi-daemon.conf. Hopefully there is "LessConf" to do on 5100 other distros/OS's... 5101 5102 5103 Q-62: Can I have x11vnc allow a user to log in with her UNIX username 5104 and password and then have it find her X session display on that 5105 machine and then attach to it? How about starting an X session if one 5106 cannot be found? 5107 5108 The easiest way to do this is via inetd(8) using the -unixpw and 5109 -display WAIT options. The reason inetd(8) makes this easier is that 5110 it starts a new x11vnc process for each new user connection. Otherwise 5111 a wrapper would have to listen for connections and spawn new x11vnc's 5112 (see this example and also the -loopbg option.) inetd(8) is not 5113 required for this, but it makes some aspects more general. 5114 5115 Also with inetd(8) users always connect to a fixed VNC display, say 5116 hostname:0, and do not need to memorize a special VNC display number 5117 just for their personal use, etc. 5118 5119 Update: Use the -find, -create, -svc, and -xdmsvc options that are 5120 shorthand for common FINDCREATEDISPLAY usage modes (e.g. terminal 5121 services) described below. (i.e. simply use "-svc" instead of the 5122 cumbersome "-display WAIT:cmd=FINDCREATEDISPLAY-Xvfb -unixpw -users 5123 unixpw= -ssl SAVE") 5124 5125 The -display WAIT option makes x11vnc wait until a VNC viewer is 5126 connected before attaching to the X display. 5127 5128 Additionally it can be used to run an external command that returns 5129 the DISPLAY and XAUTHORITY data. We provide some useful builtin ones 5130 (FINDDISPLAY and FINDCREATEDISPLAY below), but in principle one could 5131 supply his own script: "-display WAIT:cmd=/path/to/find_display" where 5132 the script find_display might look something like this. 5133 5134 A default script somewhat like the above is used under "-display 5135 WAIT:cmd=FINDDISPLAY" (same as -find) The format for any such command 5136 is that it returns DISPLAY=:disp as the first line and any remaining 5137 lines are either XAUTHORITY=file or raw xauth data (the above example 5138 does the latter.) If applicable (-unixpw mode), the program is run as 5139 the Unix user name who logged in. 5140 5141 On Linux if the virtual terminal is known the program appends ",VT=n" 5142 to the DISPLAY line; a chvt n will be attempted automatically. Or if 5143 only the X server process ID is known it appends ",XPID=n" (a chvt 5144 will be attempted by x11vnc.) 5145 5146 Tip: Note that the -find option is an alias for "-display 5147 WAIT:cmd=FINDDISPLAY". Use it! 5148 5149 The -unixpw option allows UNIX password logins. It conveniently knows 5150 the Unix username whose X display should be found. Here are a couple 5151 /etc/inetd.conf examples of this usage: 5152 5900 stream tcp nowait nobody /usr/sbin/tcpd /usr/local/bin/x11vnc -inetd 5153 -unixpw \ 5154 -find -o /var/log/x11vnc.log -ssl SAVE -ssldir /usr/local/certs 5155 5900 stream tcp nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc -inetd 5156 -unixpw \ 5157 -find -o /var/log/x11vnc.log -ssl SAVE -users unixpw= 5158 5159 Note we have used the -find alias and the very long lines have been 5160 split. An alternative is to use a wrapper script, e.g. 5161 /usr/local/bin/x11vnc.sh that has all of the options. (see also the 5162 -svc alias.) 5163 5164 In the first inetd line x11vnc is run as user "nobody" and stays user 5165 nobody during the whole session. The permissions of the log files and 5166 certs directory will need to be set up to allow "nobody" to use them. 5167 5168 In the second one x11vnc is run as root and switches to the user that 5169 logs in due to the "-users unixpw=" option. 5170 5171 Note that SSL is required for this mode because otherwise the Unix 5172 password would be passed in clear text over the network. In general 5173 -unixpw is not required for this sort of scheme, but it is convenient 5174 because it determines exactly who the Unix user is whose display 5175 should be sought. Otherwise the find_display script would have to use 5176 some method to work out DISPLAY, XAUTHORITY, etc (perhaps you use 5177 multiple inetd ports and hardwire usernames for different ports.) 5178 5179 If you really want to disable the SSL or SSH -localhost constraints 5180 (this is not recommended unless you really know what you are doing: 5181 Unix passwords sent in clear text is a very bad idea...) read the 5182 -unixpw documentation. 5183 5184 A inetd(8) scheme for a fixed user that doesn't use SSL or unix 5185 passwds could be: 5186 /usr/local/bin/x11vnc -inetd -users =fred -find -rfbauth /home/fred/.vnc/pass 5187 wd -o /var/log/x11vnc.log 5188 5189 The "-users =fred" option will cause x11vnc to switch to user fred and 5190 then find his X display. The VNC password (-rfbauth) as opposed to 5191 Unix password (-unixpw) is used to authenticate the VNC client. 5192 5193 Similar looking commands to the above examples can be run directly and 5194 do not use inetd (just remove the -inetd option and run from the 5195 cmdline, etc.) 5196 5197 5198 X Session Creation: An added (Nov/2006) extension to FINDDISPLAY is 5199 FINDCREATEDISPLAY where if it does not find an X display via the 5200 FINDDISPLAY method it will create an X server session for the user 5201 (i.e. desktop/terminal server.) This is the only time x11vnc actually 5202 tries to start up an X server (normally it just attaches to an 5203 existing one.) 5204 5205 For virtual sessions you will need to install the Xvfb program (e.g. 5206 apt-get install xvfb) or our Xdummy program (see below.) 5207 5208 By default it will only try to start up virtual (non-hardware) X 5209 servers: first Xvfb and if that is not available then Xdummy (included 5210 in the x11vnc source code.) Note that Xdummy only works on Linux 5211 whereas Xvfb works just about everywhere (and in some situations 5212 Xdummy must be run as root.) An advantage of Xdummy over Xvfb is that 5213 Xdummy supports RANDR dynamic screen resizing, which can be handy if 5214 the user accesses the desktop from different sized screens (e.g. 5215 workstation and laptop.) 5216 5217 So an inetd(8) example might look like: 5218 5900 stream tcp nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc -inetd \ 5219 -o /var/log/x11vnc.log -http -prog /usr/local/bin/x11vnc \ 5220 -ssl SAVE -unixpw -users unixpw= -display WAIT:cmd=FINDCREATEDISPLAY 5221 5222 Where the very long lines have been split. See below where that long 5223 and cumbersome last line is replaced by the -svc alias. 5224 5225 The above mode will allow direct SSL (e.g. ss_vncviewer or SSVNC) 5226 access and also Java Web browers access via: https://hostname:5900/. 5227 5228 Tip: Note that the -create option is an alias for "-display 5229 WAIT:cmd=FINDCREATEDISPLAY-Xvfb". 5230 5231 Tip: Note that -svc is a short hand for the long "-ssl SAVE -unixpw 5232 -users unixpw= -display WAIT:cmd=FINDCREATEDISPLAY" part. Unlike 5233 -create, this alias also sets up SSL encryption and Unix password 5234 login. 5235 5236 The above inetd example then simplifies to: 5237 5900 stream tcp nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc -inetd \ 5238 -o /var/log/x11vnc.log -http -prog /usr/local/bin/x11vnc \ 5239 -svc 5240 5241 Tip: In addition to the usual unixpw parameters, inside the VNC viewer 5242 the user can specify after his username (following a ":" see -display 5243 WAIT for details) for FINDCREATEDISPLAY they can add "geom=WxH" or 5244 "geom=WxHxD" to specify the width, height, and optionally the color 5245 depth. E.g. "fred:geom=800x600" at the login: prompt. Also if the env. 5246 var X11VNC_CREATE_GEOM is set to the desired WxH or WxHxD that will be 5247 used by x11vnc. 5248 5249 You can set the env. var X11VNC_SKIP_DISPLAY to a comma separated list 5250 of displays to ignore in the FINDDISPLAY process (to force creation of 5251 new displays in some cases.) The user logging in via the vncviewer can 5252 also set this via username:nodisplay=...) 5253 5254 If you do not plan on using the Java Web browser applet you can remove 5255 the -http (and -prog) option since this will speed up logging-in by a 5256 few seconds (x11vnc will not have to wait to see if a connection is 5257 HTTPS or VNC.) 5258 5259 For reference, xinetd format in the file, say, /etc/xinetd.d/x11vnc: 5260 service x11vnc 5261 { 5262 type = UNLISTED 5263 port = 5900 5264 socket_type = stream 5265 protocol = tcp 5266 wait = no 5267 user = root 5268 server = /usr/local/bin/x11vnc 5269 server_args = -inetd -o /var/log/x11vnc.log -http -prog /usr/local/ 5270 bin/x11vnc -svc 5271 disable = no 5272 } 5273 5274 To print out the script in this case use "-display 5275 WAIT:cmd=FINDCREATEDISPLAY-print". To change the preference of 5276 Xservers and which to try list them, e.g.: "-display 5277 WAIT:cmd=FINDCREATEDISPLAY-X,Xvfb,Xdummy" or use "-create_xsrv 5278 X,Xvfb,Xdummy". The "X" one means to try to start up a real, hardware 5279 X server, e.g. startx(1) (if there is already a real X server running 5280 this may only work on Linux and the chvt program may need to be run to 5281 switch to the correct Linux virtual terminal.) x11vnc will try to run 5282 chvt automatically if it can determine which VT should be switched to. 5283 5284 XDM/GDM/KDM Login Greeter Panel: If you want to present the user with 5285 a xdm/gdm/kdm display manager "greeter" login you can use Xvfb.xdmcp 5286 instead of Xvfb, etc in the above list. However, you need to configure 5287 xdm/gdm/kdm to accept localhost XDMCP messages, this can be done by 5288 (from -help output): 5289 If you want the FINDCREATEDISPLAY session to contact an XDMCP login 5290 manager (xdm/gdm/kdm) on the same machine, then use "Xvfb.xdmcp" 5291 instead of "Xvfb", etc. The user will have to supply his username 5292 and password one more time (but he gets to select his desktop 5293 type so that can be useful.) For this to work, you will need to 5294 enable localhost XDMCP (udp port 177) for the display manager. 5295 This seems to be: 5296 5297 for gdm in gdm.conf: Enable=true in section [xdmcp] 5298 for kdm in kdmrc: Enable=true in section [Xdmcp] 5299 for xdm in xdm-config: DisplayManager.requestPort: 177 5300 5301 Unless you are also providing XDMCP service to xterminals or other 5302 machines, make sure that the host access list only allows local 5303 connections (the name of this file is often Xaccess and it is usually 5304 setup by default to do just that.) Nowadays, host level firewalling 5305 will also typically block UDP (port 177 for XDMCP) by default 5306 effectively limiting the UDP connections to localhost. 5307 5308 Tip: Note that -xdmsvc is a short hand alias for the long "-ssl SAVE 5309 -unixpw -users unixpw= -display 5310 WAIT:cmd=FINDCREATEDISPLAY-Xvfb.xdmcp". So we simply use: 5311 service x11vnc 5312 { 5313 type = UNLISTED 5314 port = 5900 5315 socket_type = stream 5316 protocol = tcp 5317 wait = no 5318 user = root 5319 server = /usr/local/bin/x11vnc 5320 server_args = -inetd -o /var/log/x11vnc.log -xdmsvc 5321 disable = no 5322 } 5323 5324 (Note: use "-svc" instead of "-xdmsvc" for no XDMCP login greeter.) 5325 5326 5327 Local access (VNC Server and VNC Viewer on the same machine): To 5328 access your virtual X display session locally (i.e. while sitting at 5329 the same machine it is running on) one can perhaps have something like 5330 this in their $HOME/.xinitrc 5331 #!/bin/sh 5332 x11vnc -create -rfbport 5905 -env WAITBG=1 5333 vncviewer -geometry +0+0 -encodings raw -passwd $HOME/.vnc/passwd localhost:5 5334 5335 You may not need the -passwd. Recent RealVNC viewers might be this: 5336 #!/bin/sh 5337 x11vnc -create -rfbport 5905 -env WAITBG=1 5338 vncviewer -FullScreen -PreferredEncoding raw -passwd $HOME/.vnc/passwd localhos 5339 t:5 5340 5341 This way a bare X server is run with no window manager or desktop; it 5342 simply runs only the VNC Viewer on the real X server. The Viewer then 5343 draws the virtual X session on to the real one. On your system it 5344 might not be $HOME/.xinitrc, but rather .xsession, .Xclients, or 5345 something else. You will need to figure out what it is for your system 5346 and configuration. 5347 5348 There may be a problem if the resolution (WxH) of the virtual X 5349 display does not match that of the physical X display. 5350 5351 If you do not want to or cannot figure out the X startup script name 5352 (.xinitrc, etc) you could save the above commands to a shell script, 5353 say "vnclocal", and the log in via the normal KDM or GDM greeter 5354 program using the "Failsafe" option. Then in the lone xterm that comes 5355 up type "vnclocal" to connect to your virtual X display via x11vnc and 5356 vncviewer. 5357 5358 _________________________________________________________________ 5359 5360 Summary: The "-display WAIT:cmd=FINDCREATEDISPLAY" scheme can be used 5361 to provide a "desktop service" (i.e. terminal service) on the server 5362 machine: you always get some desktop there, either a real hardware X 5363 server or a virtual one (depending on how you set things up.) 5364 5365 So it provides simple "terminal services" based on Unix username and 5366 password. The created X server sessions (virtual or real hardware) 5367 will remain running after you disconnect the VNC viewer and will be 5368 found again on reconnecting via VNC and logging in. To terminate them 5369 use the normal way to Exit/LogOut from inside your X session. The user 5370 does not have to memorize which VNC display number is his. They all go 5371 the same one (e.g. hostname:0) and it switches based on username. 5372 5373 5374 Q-63: Can I have x11vnc restart itself after it terminates? 5375 5376 One could do this in a shell script, but now there is an option -loop 5377 that makes it easier. Of course when x11vnc restarts it needs to have 5378 permissions to connect to the (potentially new) X display. This mode 5379 could be useful if the X server restarts often. Use e.g. "-loop5000" 5380 to sleep 5000 ms between restarts. Also "-loop2000,5" to sleep 2000 ms 5381 and only restart 5 times. 5382 5383 One can also use the -loopbg to emulate inetd(8) to some degree, where 5384 each connected process runs in the background. It could be combined, 5385 say, with the -svc option to provide simple terminal services without 5386 using inetd(8). 5387 5388 5389 Q-64: How do I make x11vnc work with the Java VNC viewer applet in a 5390 web browser? 5391 5392 To have x11vnc serve up a Java VNC viewer applet to any web browsers 5393 that connect to it, run x11vnc with this option: 5394 -httpdir /path/to/the/java/classes/dir 5395 5396 (this directory will contain the files index.vnc and, for example, 5397 VncViewer.jar) Note that libvncserver contains the TightVNC Java 5398 classes jar file for your convenience. (it is the file 5399 classes/VncViewer.jar in the source tree.) 5400 5401 You will see output something like this: 5402 14/05/2004 11:13:56 Autoprobing selected port 5900 5403 14/05/2004 11:13:56 Listening for HTTP connections on TCP port 5800 5404 14/05/2004 11:13:56 URL http://walnut:5800 5405 14/05/2004 11:13:56 screen setup finished. 5406 14/05/2004 11:13:56 The VNC desktop is walnut:0 5407 PORT=5900 5408 5409 then you can connect to that URL with any Java enabled browser. Feel 5410 free to customize the default index.vnc file in the classes directory. 5411 5412 As of May/2005 the -http option will try to guess where the Java 5413 classes jar file is by looking in expected locations and ones relative 5414 to the x11vnc binary. 5415 5416 Also note that if you wanted to, you could also start the Java viewer 5417 entirely from the viewer-side by having the jar file there and using 5418 either the java or appletviewer commands to run the program. 5419 java -cp ./VncViewer.jar VncViewer HOST far-away.east PORT 5900 5420 5421 Proxies: See the discussion here if the web browser must use a web 5422 proxy to connect to the internet. It is tricky to get Java applets to 5423 work in this case: a signed applet must be used so it can connect to 5424 the proxy and ask for the redirection to the VNC server. One way to do 5425 this is to use the signed SSL one referred to in classes/ssl/proxy.vnc 5426 and set disableSSL=yes (note that this has no encryption; please use 5427 SSL or SSH as discuss elsewhere on this page) in the URL or the file. 5428 5429 5430 Q-65: Are reverse connections (i.e. the VNC server connecting to the 5431 VNC viewer) using "vncviewer -listen" and vncconnect(1) supported? 5432 5433 As of Mar/2004 x11vnc supports reverse connections. On Unix one starts 5434 the VNC viewer in listen mode: "vncviewer -listen" (see your 5435 documentation for Windows, etc), and then starts up x11vnc with the 5436 -connect option. To connect immediately at x11vnc startup time use the 5437 "-connect host:port" option (use commas for a list of hosts to connect 5438 to.) The ":port" is optional (default is VNC listening port is 5500.) 5439 5440 If a file is specified instead: -connect /path/to/some/file then that 5441 file is checked periodically (about once a second) for new hosts to 5442 connect to. 5443 5444 The -remote control option (aka -R) can also be used to do this during 5445 an active x11vnc session, e.g.: 5446 x11vnc -display :0 -R connect:hostname.domain 5447 5448 Use the "-connect_or_exit" option to have x11vnc exit if the reverse 5449 connection fails. Also, note the "-rfbport 0" option disables TCP 5450 listening for connections (potentially useful for reverse connection 5451 mode, assuming you do not want any "forward" connections.) 5452 5453 Note that as of Mar/2006 x11vnc requires password authentication for 5454 reverse connections as well as for forward ones (assuming password 5455 auth has been enabled, e.g. via -rfbauth, -passwdfile, etc.) Many VNC 5456 servers do not require any password for reverse connections. To regain 5457 the old behavior supply this option "-env 5458 X11VNC_REVERSE_CONNECTION_NO_AUTH=1" to x11vnc. 5459 5460 Vncconnect command: To use the vncconnect(1) program (from the core 5461 VNC package at www.realvnc.com) specify the -vncconnect option to 5462 x11vnc (Note: as of Dec/2004 -vncconnect is now the default.) 5463 vncconnect(1) must be pointed to the same X11 DISPLAY as x11vnc (since 5464 it uses X properties to communicate with x11vnc.) If you do not have 5465 or do not want to get the vncconnect(1) program, the following script 5466 (named "Vncconnect") may work if your xprop(1) supports the -set 5467 option: 5468 #!/bin/sh 5469 # usage: Vncconnect <host> 5470 # Vncconnect <host:port> 5471 # note: not all xprop(1) support -set. 5472 # 5473 xprop -root -f VNC_CONNECT 8s -set VNC_CONNECT "$1" 5474 5475 5476 Q-66: Can reverse connections be made to go through a Web or SOCKS 5477 proxy or SSH? 5478 5479 Yes, as of Oct/2007 x11vnc supports reverse connections through 5480 proxies: use the "-proxy host:port" option. The default is to assume 5481 the proxy is a Web proxy. Note that most Web proxies only allow proxy 5482 destination connections to ports 443 (HTTPS) and 563 (SNEWS) and so 5483 this might not be too useful unless the proxy has been modified 5484 (AllowCONNECT apache setting) or the VNC viewer listens on one of 5485 those ports (or the router does a port redir.) A web proxy may also be 5486 specified via "-proxy http://host:port" 5487 5488 For SOCKS4 and SOCKS4a proxies use this format "-proxy 5489 socks://host:port". If the reverse connection hostname is a numerical 5490 IP or "localhost" then SOCKS4 (no host lookup) is used, otherwise 5491 SOCKS4a will be used. For SOCKS5 (proxy will do lookup and many other 5492 things) use "-proxy socks5://host:port". Note that the SSH builtin 5493 SOCKS proxy "ssh -D port" only does SOCKS4 or SOCKS5, so use socks5:// 5494 for a ssh -D proxy. 5495 5496 The proxying works for both SSL encrypted and normal reverse 5497 connections. 5498 5499 An experimental mode is "-proxy http://host:port/..." where the URL 5500 (e.g. a CGI script) is retrieved via the GET method. See -proxy for 5501 more info. 5502 5503 Another experimental mode is "-proxy ssh://user@host" in which case a 5504 SSH tunnel is used for the proxying. See -proxy for more info. 5505 5506 Up to 3 proxies may be chained together by listing them by commas 5507 e.g.: "-proxy http://host1:port1,socks5://host2:port2" in case one 5508 needs to ricochet off of several machines to ultimately reach the 5509 listening viewer. 5510 5511 5512 Q-67: Can x11vnc provide a multi-user desktop web login service as an 5513 Apache CGI or PHP script? 5514 Yes. See the example script desktop.cgi for ideas. It is in the source 5515 tree in the directory x11vnc/misc. It serves x11vnc's SSL enabled Java 5516 Applet to the web browser with the correct connection information for 5517 the user's virtual desktop (an Xvfb session via -create; be sure to 5518 add the Xvfb package.) HTTPS/SSL enabled Apache should be used to 5519 serve the script to avoid unix and vnc passwords from being sent in 5520 cleartext and sniffed. 5521 5522 By default it uses a separate VNC port for each user desktop (either 5523 by autoprobing in a range of ports or using a port based on the userid 5524 number.) The web server's firewall must allow incoming connections to 5525 these ports. 5526 5527 It is somewhat difficult to do all of this with x11vnc listening on a 5528 single port, however there is also a 'fixed port' scheme described in 5529 the script based on -loopbg that works fairly well (but more 5530 experience is needed to see what problems contention for the same port 5531 causes; however at worst one user may need to re-login.) 5532 5533 There is also an optional 'port redirection' mode for desktop.cgi that 5534 allows redirection to other machines inside the firewall already 5535 running SSL enabled VNC servers. This provides much of the 5536 functionality as the SSL Portal and is easier to set up. 5537 5538 5539 Q-68: Can I use x11vnc as a replacement for Xvnc? (i.e. not for a real 5540 display, but for a virtual one I keep around.) 5541 5542 You can, but you would not be doing this for performance reasons (for 5543 virtual X sessions via VNC, Xvnc should give the fastest response.) 5544 You may want to do this because Xvnc is buggy and crashes, does not 5545 support an X server extension you desire, or you want to take 5546 advantage of one of x11vnc's unending number of options and features. 5547 5548 One way to achieve this is to have a Xvfb(1) virtual framebuffer X 5549 server running in the background and have x11vnc attached to it. 5550 Another method, faster and more accurate, is to use the "dummy" Device 5551 Driver in XFree86/Xorg (see below.) 5552 5553 For these virtual sessions you will need to install the Xvfb program 5554 (e.g. apt-get install xvfb) or our Xdummy program (see below.) 5555 5556 In either case, one can view this desktop both remotely and also 5557 locally using vncviewer. Make sure vncviewer's "-encodings raw" is in 5558 effect for local viewing (compression seems to slow things down 5559 locally.) For local viewing you set up a "bare" window manager that 5560 just starts up vncviewer and nothing else (See how below.) 5561 5562 Here is one way to start up Xvfb: 5563 xinit -- /usr/bin/Xvfb :1 -cc 4 -screen 0 1024x768x16 5564 5565 This starts up a 16bpp virtual display. To export it via VNC use 5566 x11vnc -display :1 ... 5567 5568 Then have the remote vncviewer attach to x11vnc's VNC display (e.g. :0 5569 which is port 5900.) 5570 5571 The "-cc 4" Xvfb option is to force it to use a TrueColor visual 5572 instead of DirectColor (this works around a recent bug in the Xorg 5573 Xvfb server.) 5574 5575 One good thing about Xvfb is that the virtual framebuffer exists in 5576 main memory (rather than in the video hardware), and so x11vnc can 5577 "screen scrape" it very efficiently (more than, say, 100X faster than 5578 normal video hardware.) 5579 5580 Update Nov/2006: See the FINDCREATEDISPLAY discussion of the "-display 5581 WAIT:cmd=FINDDISPLAY" option where virtual (Xvfb or Xdummy, or even 5582 real ones by changing an option) X servers are started automatically 5583 for new users connecting. This provides a "desktop service" for the 5584 machine. You either get your real X session or your virtual 5585 (Xvfb/Xdummy) one whenever you connect to the machine (inetd(8) is a 5586 nice way to provide this service.) The -find, -create, -svc, and 5587 -xdmsvc aliases can also come in handy here. 5588 5589 There are some annoyances WRT Xvfb however. The default keyboard 5590 mapping seems to be very poor. One should run x11vnc with -add_keysyms 5591 option to have keysyms added automatically. Also, to add the Shift_R 5592 and Control_R modifiers something like this is needed: 5593 #!/bin/sh 5594 xmodmap -e "keycode any = Shift_R" 5595 xmodmap -e "add Shift = Shift_L Shift_R" 5596 xmodmap -e "keycode any = Control_R" 5597 xmodmap -e "add Control = Control_L Control_R" 5598 xmodmap -e "keycode any = Alt_L" 5599 xmodmap -e "keycode any = Alt_R" 5600 xmodmap -e "keycode any = Meta_L" 5601 xmodmap -e "add Mod1 = Alt_L Alt_R Meta_L" 5602 5603 (note: these are applied automatically in the FINDCREATEDISPLAY mode 5604 of x11vnc.) Perhaps the Xvfb options -xkbdb or -xkbmap could be used 5605 to get a better default keyboard mapping... 5606 5607 Dummy Driver: A user points out a faster and more accurate method is 5608 to use the "dummy" Device Driver of XFree86/Xorg instead of Xvfb. He 5609 uses this to create a persistent and resizable desktop accessible from 5610 anywhere. In the Device Section of the config file set Driver "dummy". 5611 You may also need to set VideoRam NNN to be large enough to hold the 5612 framebuffer. The framebuffer is kept in main memory like Xvfb except 5613 that the server code is closely correlated with the real XFree86/Xorg 5614 Xserver unlike Xvfb. 5615 5616 The main drawback to this method (besides requiring extra 5617 configuration and possibly root permission) is that it also does the 5618 Linux Virtual Console/Terminal (VC/VT) switching even though it does 5619 not need to (since it doesn't use a real framebuffer.) There are some 5620 "dual headed" (actually multi-headed/multi-user) patches to the X 5621 server that turn off the VT usage in the X server. Update: As of 5622 Jul/2005 we have an LD_PRELOAD script Xdummy that allows you to use a 5623 stock (i.e. unpatched) Xorg or XFree86 server with the "dummy" driver 5624 and not have any VT switching problems! An advantage of Xdummy over 5625 Xvfb is that Xdummy supports RANDR dynamic screen resizing. 5626 5627 The standard way to start the "dummy" driver would be: 5628 startx -- :1 -config /etc/X11/xorg.conf.dummy 5629 5630 where the file /etc/X11/xorg.conf.dummy has its Device Section 5631 modified as described above. To use the LD_PRELOAD wrapper script: 5632 startx -- /path/to/Xdummy :1 5633 5634 An xdm(1) example is also provided. 5635 5636 In general, one can use these sorts of schemes to use x11vnc to export 5637 other virtual X sessions, say Xnest or even Xvnc itself (useful for 5638 testing x11vnc.) 5639 5640 Local access (VNC Server and VNC Viewer on the same machine): You use 5641 a VNC viewer to access the display remotely; to access your virtual X 5642 display locally (i.e. while sitting at the same machine it is running 5643 on) one can perhaps have something like this in their $HOME/.xinitrc 5644 #!/bin/sh 5645 x11vnc -display :5 -rfbport 5905 -bg 5646 vncviewer -geometry +0+0 -encodings raw -passwd $HOME/.vnc/passwd localhost:5 5647 5648 The display numbers (VNC and X) will likely be different (you could 5649 also try -find), and you may not need the -passwd. Recent RealVNC 5650 viewers might be this: 5651 #!/bin/sh 5652 x11vnc -display :5 -rfbport 5905 -bg 5653 vncviewer -FullScreen -PreferredEncoding raw -passwd $HOME/.vnc/passwd localhos 5654 t:5 5655 5656 This way a bare X server is run with no window manager or desktop; it 5657 simply runs only the VNC Viewer on the real X server. The Viewer then 5658 draws the virtual X session on to the real one. On your system it 5659 might not be $HOME/.xinitrc, but rather .xsession, .Xclients, or 5660 something else. You will need to figure out what it is for your system 5661 and configuration. 5662 5663 5664 XDM/GDM/KDM One-Shot X sessions: For the general replacement of Xvnc 5665 by Xvfb+x11vnc, one user describes a similar setup he created where 5666 the X sessions are one-shot's (destroyed after the vncviewer 5667 disconnects) and it uses the XDM/GDM/KDM login greeter here. 5668 5669 5670 Q-69: How can I use x11vnc on "headless" machines? Why might I want 5671 to? 5672 5673 An interesting application of x11vnc is to let it export displays of 5674 "headless" machines. For example, you may have some lab or server 5675 machines with no keyboard, mouse, or monitor, but each one still has a 5676 video card. One can use x11vnc to provide a simple "desktop service" 5677 from these server machines. 5678 5679 An X server can be started on the headless machine (sometimes this 5680 requires configuring the X server to not fail if it cannot detect a 5681 keyboard or mouse, see the next paragraph.) Then you can export that X 5682 display via x11vnc (e.g. see this FAQ) and access it from anywhere on 5683 the network via a VNC viewer. 5684 5685 Some tips on getting X servers to start on machines without keyboard 5686 or mouse: For XFree86/Xorg the Option "AllowMouseOpenFail" "true" 5687 "ServerFlags" config file option is useful. On Solaris Xsun the 5688 +nkeyboard and +nmouse options are useful (put them in the server 5689 command line args in /etc/dt/config/Xservers.) There are patches 5690 available for Xsun at lease back to Solaris 8 that support this. See 5691 Xserver(1) for more info. 5692 5693 Although this usage may sound strange it can be quite useful for a GUI 5694 (or other) testing or QA setups: the engineers do not need to walk to 5695 lab machines running different hardware, OS's, versions, etc (or have 5696 many different machines in their office.) They just connect to the 5697 various test machines over the network via VNC. The advantage to 5698 testing this way instead of using Xvnc or even Xvfb is that the test 5699 is done using the real X server, fonts, video hardware, etc. that will 5700 be used in the field. 5701 5702 One can imagine a single server machine crammed with as many video 5703 cards as it can hold to provide multiple simultaneous access or 5704 testing on different kinds of video hardware. 5705 5706 See also the FINDCREATEDISPLAY discussion of the "-display 5707 WAIT:cmd=FINDDISPLAY" option where virtual Xvfb or Xdummy, or real X 5708 servers are started automatically for new users connecting. The -find, 5709 -create, -svc, and -xdmsvc aliases can also come in handy here. 5710 5711 [Resource Usage and Performance] 5712 5713 Q-70: I have lots of memory, but why does x11vnc fail with shmget: 5714 No space left on device or Minor opcode of failed request: 1 5715 (X_ShmAttach)? 5716 5717 It is not a matter of free memory, but rather free shared memory (shm) 5718 slots, also known as shm segments. This often occurs on a public 5719 Solaris machine using the default of only 100 slots. You (or the owner 5720 or root) can clean them out with ipcrm(1). x11vnc tries hard to 5721 release its slots, but it, and other programs, are not always able to 5722 (e.g. if kill -9'd.) 5723 5724 Sometimes x11vnc will notice the problem with shm segments and tries 5725 to get by with fewer, only giving a warning like this: 5726 19/03/2004 10:10:58 shmat(tile_row) failed. 5727 shmat: Too many open files 5728 19/03/2004 10:10:58 error creating tile-row shm for len=4 5729 19/03/2004 10:10:58 reverting to single_copytile mode 5730 5731 Here is a shell script shm_clear to list and prompt for removal of 5732 your unattached shm segments (attached ones are skipped.) I use it 5733 while debugging x11vnc (I use "shm_clear -y" to assume "yes" for each 5734 prompt.) If x11vnc is regularly not cleaning up its shm segments, 5735 please contact me so we can work to improve the situation. 5736 5737 Longer term, on Solaris you can put something like this in 5738 /etc/system: 5739 set shmsys:shminfo_shmmax = 0x2000000 5740 set shmsys:shminfo_shmmni = 0x1000 5741 5742 to sweep the problem under the rug (4096 slots.) On Linux, examine 5743 /proc/sys/kernel/shmmni; you can modify the value by writing to that 5744 file. 5745 5746 Things are even more tight on Solaris 8 and earlier, there is a 5747 default maximum number of shm segments per process of 6. The error is 5748 the X server (not x11vnc) being unable to attach to the segments, and 5749 looks something like this: 5750 30/04/2004 14:04:26 Got connection from client 192.168.1.23 5751 30/04/2004 14:04:26 other clients: 5752 X Error of failed request: BadAccess (attempt to access private resource den 5753 ied) 5754 Major opcode of failed request: 131 (MIT-SHM) 5755 Minor opcode of failed request: 1 (X_ShmAttach) 5756 Serial number of failed request: 14 5757 Current serial number in output stream: 17 5758 5759 This tight limit on Solaris 8 can be increased via: 5760 set shmsys:shminfo_shmseg = 100 5761 5762 in /etc/system. See the next paragraph for more workarounds. 5763 5764 To minimize the number of shm segments used by x11vnc try using the 5765 -onetile option (corresponds to only 3 shm segments used, and adding 5766 -fs 1.0 knocks it down to 2.) If you are having much trouble with shm 5767 segments, consider disabling shm completely via the -noshm option. 5768 Performance will be somewhat degraded but when done over local machine 5769 sockets it should be acceptable (see an earlier question discussing 5770 -noshm.) 5771 5772 5773 Q-71: How can I make x11vnc use less system resources? 5774 5775 The -nap (now on by default; use -nonap to disable) and "-wait n" 5776 (where n is the sleep between polls in milliseconds, the default is 30 5777 or so) option are good places to start. In addition, something like 5778 "-sb 15" will cause x11vnc to go into a deep-sleep mode after 15 5779 seconds of no activity (instead of the default 60.) 5780 5781 Reducing the X server bits per pixel depth (e.g. to 16bpp or even 5782 8bpp) will further decrease memory I/O and network I/O. The ShadowFB X 5783 server setting will make x11vnc's screen polling less severe. Using 5784 the -onetile option will use less memory and use fewer shared memory 5785 slots (add -fs 1.0 for one less slot.) 5786 5787 5788 Q-72: How can I make x11vnc use MORE system resources? 5789 5790 You can try -threads (note this mode can be unstable and/or crash; and 5791 as of May/2008 is strongly discouraged, see the option description) or 5792 dial down the wait time (e.g. -wait 1) and possibly dial down -defer 5793 as well. Note that if you try to increase the "frame rate" too much 5794 you can bog down the server end with the extra work it needs to do 5795 compressing the framebuffer data, etc. 5796 5797 That said, it is possible to "stream" video via x11vnc if the video 5798 window is small enough. E.g. a 256x192 xawtv TV capture window (using 5799 the x11vnc -id option) can be streamed over a LAN or wireless at a 5800 reasonable frame rate. If the graphics card's framebuffer read rate is 5801 faster than normal then the video window size and frame rate can be 5802 much higher. The use of TurboVNC and/or TurboJPEG can make the frame 5803 rate somewhat higher still (but most of this hinges on the graphics 5804 card's read rate.) 5805 5806 5807 Q-73: I use x11vnc over a slow link with high latency (e.g. dialup 5808 modem or broadband), is there anything I can do to speed things up? 5809 5810 Some things you might want to experiment with (many of which will help 5811 performance on faster links as well): 5812 5813 X server/session parameters: 5814 * Configure the X server bits per pixel to be 16bpp or even 8bpp. 5815 (reduces amount of data needed to be polled, compressed, and sent) 5816 * Use a smaller desktop size (e.g. 1024x768 instead of 1280x1024) 5817 * Make sure the desktop background is a solid color (the background 5818 is resent every time it is re-exposed.) Consider using the -solid 5819 [color] option to try to do this automatically. 5820 * Configure your window manager or desktop "theme" to not use fancy 5821 images, shading, and gradients for the window decorations, etc. 5822 Disable window animations, etc. Maybe your desktop has a "low 5823 bandwidth" theme you can easily switch into and out of. Also in 5824 Firefox disable eye-candy, e.g.: Edit -> Preferences -> Advanced 5825 -> Use Smooth Scrolling (deselect it.) 5826 * Avoid small scrolls of large windows using the Arrow keys or 5827 scrollbar. Try to use PageUp/PageDown instead. (not so much of a 5828 problem in x11vnc 0.7.2 if -scrollcopyrect is active and detecting 5829 scrolls for the application.) 5830 * If the -wireframe option is not available (earlier than x11vnc 5831 0.7.2 or you have disabled it via -nowireframe) then Disable 5832 Opaque Moves and Resizes in the window manager/desktop. 5833 * However if -wireframe is active (on by default in x11vnc 0.7.2) 5834 then you should Enable Opaque Moves and Resizes in the window 5835 manager! This seems counter-intuitive, but because x11vnc detects 5836 the move/resize events early there is a huge speedup over a slow 5837 link when Opaque Moves and Resizes are enabled. (e.g. CopyRect 5838 encoding will be used.) 5839 * Turn off Anti-aliased fonts on your system, web browser, terminal 5840 windows, etc. AA fonts do not compress as well as traditional 5841 fonts (sometimes 10X less.) 5842 * On Firefox/Mozilla (and anything else) turn off "Smooth Scroll" 5843 animations. In Firefox put in the URL "about:config" and set 5844 general.smoothScroll to false. 5845 * On Xorg/XFree86 turn on the Shadow Framebuffer to speed up 5846 reading. (Option "ShadowFB" "true" in the Device section of 5847 /etc/X11/XF86Config) This disables 2D acceleration on the physical 5848 display and so may not be worth it (if you play games, etc), but 5849 could be of use in some situations. Note: If the network link is 5850 very slow, this speedup may not be noticed. 5851 5852 VNC viewer parameters: 5853 * Use a TightVNC enabled viewer! (Actually, RealVNC 4.x viewer with 5854 ZRLE encoding is not too bad either; some claim it is faster.) 5855 * Make sure the tight (or zrle) encoding is being used (look at 5856 vncviewer and x11vnc outputs) 5857 * Request 8 bits per pixel using -bgr233 (up to 4X speedup over 5858 depth 24 TrueColor (32bpp), but colors will be off) 5859 * RealVNC 4.x viewer has some extremely low color modes (only 64 and 5860 even 8 colors.) SSVNC does too. The colors are poor, but it is 5861 usually noticeably faster than bgr233 (256 colors.) 5862 * Try increasing the TightVNC -compresslevel (compresses more on 5863 server side before sending, but uses more CPU) 5864 * Try reducing the TightVNC -quality (increases JPEG compression, 5865 but is lossy with painting artifacts) 5866 * Try other VNC encodings via -encodings (tight may be the fastest, 5867 but you should compare it to zrle and maybe some of the others) 5868 * On the machine where vncviewer is run, make sure Backing Store is 5869 enabled (Xorg/XFree86 disables it by default causing re-exposures 5870 of vncviewer to be very slow) Option "backingstore" in config 5871 file. 5872 5873 x11vnc parameters: 5874 * Make sure the -wireframe option is active (it should be on by 5875 default) and you have Opaque Moves/Resizes Enabled in the window 5876 manager. 5877 * Make sure the -scrollcopyrect option is active (it should be on by 5878 default.) This detects scrolls in many (but not all) applications 5879 an applies the CopyRect encoding for a big speedup. 5880 * Enforce a solid background when VNC viewers are connected via 5881 -solid 5882 * Try x11vnc's client-side caching client-side caching scheme: 5883 -ncache 5884 * Specify -speeds modem to force the wireframe and scrollcopyrect 5885 heuristic parameters (and any future ones) to those of a dialup 5886 modem connection (or supply the rd,bw,lat numerical values that 5887 characterize your link.) 5888 * If wireframe and scrollcopyrect aren't working, try using the more 5889 drastic -nodragging (no screen updates when dragging mouse, but 5890 sometimes you miss visual feedback) 5891 * Set -fs 1.0 (disables fullscreen updates) 5892 * Try increasing -wait or -defer (reduces the maximum "frame rate", 5893 but won't help much for large screen changes) 5894 * Try the -progressive pixelheight mode with the block pixelheight 5895 100 or so (delays sending vertical blocks since they may change 5896 while viewer is receiving earlier ones) 5897 * If you just want to watch one (simple) window use -id or -appshare 5898 (cuts down extraneous polling and updates, but can be buggy or 5899 insufficient) 5900 * Set -nosel (disables all clipboard selection exchange) 5901 * Use -nocursor and -nocursorpos (repainting the remote cursor 5902 position and shape takes resources and round trips) 5903 * On very slow links (e.g. <= 28.8) you may need to increase the 5904 -readtimeout n setting if it sometimes takes more than 20sec to 5905 paint the full screen, etc. 5906 * Do not use -fixscreen to automatically refresh the whole screen, 5907 tap three Alt_L's then the screen has painting errors (rare 5908 problem.) 5909 5910 5911 Example for the KDE desktop: 5912 5913 Launch the "KDE Control Center" utility. Sometimes this is called 5914 "Personal Settings". 5915 5916 Select "Desktop". 5917 5918 Then Select "Window Behavior". In the "Moving" Tab set these: 5919 * YES - Display content in moving windows 5920 * YES - Display content in resizing windows 5921 * NO - Display window geometry when moving or resizing 5922 * NO - Animate minimize and restore 5923 5924 In the "Translucency" Tab set: 5925 * NO - Use translucency/shadows 5926 5927 Next hit "Back" and then select "Panels". 5928 5929 In the "Appearance" Tab set: 5930 * NO - Enable icon mouseover effects 5931 * NO - Enable transparency 5932 5933 Now go all the way back up to the top and Select "Appearance & 5934 Themes". 5935 5936 Select "Background" and set: 5937 * YES - No picture 5938 * Colors: Single Color 5939 5940 Select "Fonts" and disable anti-aliased fonts if you are bold enough. 5941 5942 Select "Launch Feedback" and set: 5943 * Busy Cursor: No Busy Cursor 5944 * NO - Enable taskbar notification 5945 5946 Select "Screen Saver" and set: 5947 * Screen Saver: Blank Screen 5948 5949 Select "Style" and in the "Effects" Tab set: 5950 * NO - Enable GUI effects 5951 5952 5953 Example for the GNOME desktop: 5954 * TBD. 5955 5956 5957 Q-74: Does x11vnc support the X DAMAGE Xserver extension to find 5958 modified regions of the screen quickly and efficiently? 5959 5960 Yes, as of Mar/2005 x11vnc will use the X DAMAGE extension by default 5961 if it is available on the display. This requires libXdamage to be 5962 available in the build environment as well (recent Linux distros and 5963 Solaris 10 have it.) 5964 5965 The DAMAGE extension enables the X server to report changed regions of 5966 the screen back to x11vnc. So x11vnc doesn't have to guess where the 5967 changes are (by polling every pixel of the entire screen every 2-4 5968 seconds.) The use of X DAMAGE dramatically reduces the load when the 5969 screen is not changing very much (i.e. most of the time.) It also 5970 noticeably improves updates, especially for very small changed areas 5971 (e.g. clock ticking, cursor flashing, typing, etc.) 5972 5973 Note that the DAMAGE extension does not speed up the actual reading of 5974 pixels from the video card framebuffer memory, by, say, mirroring them 5975 in main memory. So reading the fb is still painfully slow (e.g. 5976 5MB/sec), and so even using X DAMAGE when large changes occur on the 5977 screen the bulk of the time is still spent retrieving them. Not ideal, 5978 but use of the ShadowFB XFree86/Xorg option speeds up the reading 5979 considerably (at the cost of h/w acceleration.) 5980 5981 Unfortunately the current Xorg DAMAGE extension implementation can at 5982 times be overly conservative and report very large rectangles as 5983 "damaged" even though only a small portion of the pixels have actually 5984 been modified. This behavior is often the fault of the window manager 5985 (e.g. it redraws the entire, unseen, frame window underneath the 5986 application window when it gains focus), or the application itself 5987 (e.g. does large, unnecessary repaints.) 5988 5989 To work around this deficiency, x11vnc currently only trusts small 5990 DAMAGE rectangles to contain real damage. The larger rectangles are 5991 only used as hints to focus the traditional scanline polling (i.e. if 5992 a scanline doesn't intersect a recent DAMAGE rectangle, the scan is 5993 skipped.) You can use the "-xd_area A" option to adjust the size of 5994 the trusted DAMAGE rectangles. The default is 20000 pixels (e.g. a 5995 140x140 square, etc.) Use "-xd_area 0" to disable the cutoff and trust 5996 all DAMAGE rectangles. 5997 5998 The option "-xd_mem f" may also be of use in tuning the algorithm. To 5999 disable using DAMAGE entirely use "-noxdamage". 6000 6001 6002 Q-75: My OpenGL application shows no screen updates unless I supply 6003 the -noxdamage option to x11vnc. 6004 One user reports in his environment (MythTV using the NVIDIA OpenGL 6005 drivers) he gets no updates after the initial screen is drawn unless 6006 he uses the "-noxdamage" option. 6007 6008 This seems to be a bug in the X DAMAGE implementation of that driver. 6009 You may have to use -noxdamage as well. A way to autodetect this will 6010 be tried, probably the best it will do is automatically stop using X 6011 DAMAGE. 6012 6013 A developer for MiniMyth reports that the 'alphapulse' tag of the 6014 theme G.A.N.T. can also cause problems, and should be avoided when 6015 using VNC. 6016 6017 Update: see this FAQ too. 6018 6019 6020 Q-76: When I drag windows around with the mouse or scroll up and down 6021 things really bog down (unless I do the drag in a single, quick 6022 motion.) Is there anything to do to improve things? 6023 6024 This problem is primarily due to slow hardware read rates from video 6025 cards: as you scroll or move a large window around the screen changes 6026 are much too rapid for x11vnc to keep up them (it can usually only 6027 read the video card at about 5-10 MB/sec, so it can take a good 6028 fraction of a second to read the changes induce from moving a large 6029 window, if this to be done a number of times in succession the window 6030 or scroll appears to "lurch" forward.) See the description in the 6031 -pointer_mode option for more info. The next bottleneck is compressing 6032 all of these changes and sending them out to connected viewers, 6033 however the VNC protocol is pretty much self-adapting with respect to 6034 that (updates are only packaged and sent when viewers ask for them.) 6035 6036 As of Jan/2004 there are some improvements to libvncserver. The 6037 default should now be much better than before and dragging small 6038 windows around should no longer be a huge pain. If for some reason 6039 these changes make matters worse, you can go back to the old way via 6040 the "-pointer_mode 1" option. 6041 6042 Also added was the -nodragging option that disables all screen updates 6043 while dragging with the mouse (i.e. mouse motion with a button held 6044 down.) This gives the snappiest response, but might be undesired in 6045 some circumstances when you want to see the visual feedback while 6046 dragging (e.g. menu traversal or text selection.) 6047 6048 As of Dec/2004 the -pointer_mode n option was introduced. n=1 is the 6049 original mode, n=2 an improvement, etc.. See the -pointer_mode n help 6050 for more info. 6051 6052 Also, in some circumstances the -threads option can improve response 6053 considerably. Be forewarned that if more than one vncviewer is 6054 connected at the same time then libvncserver may not be thread safe 6055 (try to get the viewers to use different VNC encodings, e.g. tight and 6056 ZRLE.) This option can be unstable and so as of Feb/2008 it is 6057 disabled by default. Set env. X11VNC_THREADED=1 to re-enable. 6058 6059 As of Apr/2005 two new options (see the wireframe FAQ and 6060 scrollcopyrect FAQ below) provide schemes to sweep this problem under 6061 the rug for window moves or resizes and for some (but not all) window 6062 scrolls. These are the preferred way of avoiding the "lurching" 6063 problem, contact me if they are not working. Note on SuSE and some 6064 other distros the RECORD X extension used by scrollcopyrect is not 6065 enabled by default, turn it on in xorg.conf: 6066 Section "Module" 6067 ... 6068 Load "record" 6069 ... 6070 EndSection 6071 6072 6073 Q-77: Why not do something like wireframe animations to avoid the 6074 windows "lurching" when being moved or resized? 6075 6076 Nice idea for a hack! As of Apr/2005 x11vnc by default will apply 6077 heuristics to try to guess if a window is being (opaquely) moved or 6078 resized. If such a change is detected framebuffer polling and updates 6079 will be suspended and only an animated "wireframe" (a rectangle 6080 outline drawn where the moved/resized window would be) is shown. When 6081 the window move/resize stops, it returns to normal processing: you 6082 should only see the window appear in the new position. This spares you 6083 from interacting with a "lurching" window between all of the 6084 intermediate steps. BTW the lurching is due to slow video card read 6085 rates (see here too.) A displacement, even a small one, of a large 6086 window requires a non-negligible amount of time, a good fraction of a 6087 second, to read in from the hardware framebuffer. 6088 6089 Note that Opaque Moves/Resizes must be Enabled by your window manager 6090 for -wireframe to do any good. 6091 6092 The mode is currently on by default because most people are afflicted 6093 with the problem. It can be disabled with the -nowireframe option (aka 6094 -nowf.) Why might one want to turn off the wireframing? Since x11vnc 6095 is merely guessing when windows are being moved/resized, it may guess 6096 poorly for your window-manager or desktop, or even for the way you 6097 move the pointer. If your window-manager or desktop already does its 6098 own wireframing then this mode is a waste of time and could do the 6099 wrong thing occasionally. There may be other reasons the new mode 6100 feels unnatural. If you have very expensive video hardware (SGI, well 6101 now even proprietary Xorg drivers are fast at reading) or are using an 6102 in-RAM video framebuffer (SunRay, ShadowFB, Xvfb), the read rate from 6103 that framebuffer may be very fast (100's of MB/sec) and so you don't 6104 really see much lurching (at least over a fast LAN): opaque moves look 6105 smooth in x11vnc. Note: ShadowFB is often turned on when you are using 6106 the vesafb or fbdev XFree86 video driver instead of a native one so 6107 you might be using it already and not know. 6108 6109 The heuristics used to guess window motion or resizing are simple, but 6110 are not fool proof: x11vnc is sometimes tricked and so you'll 6111 occasionally see the lurching opaque move and rarely something even 6112 worse. 6113 6114 First it assumes that the move/resize will occur with a mouse button 6115 pressed, held down and dragged (of course this is only mostly true.) 6116 Next it will only consider a window for wireframing if the mouse 6117 pointer is initially "close enough" to the edges of the window frame, 6118 e.g. you have grabbed the title bar or a resizer edge (this 6119 requirement can be disabled and it also not applied if a modifier key, 6120 e.g. Alt, is pressed.) If these are true, it will wait an amount of 6121 time to see if the window starts moving or resizing. If it does, it 6122 starts drawing the wireframe "outline" of where the window would be. 6123 When the mouse button is released, or a timeout occurs, it goes back 6124 to the standard mode to allow the actual framebuffer changes to 6125 propagate to the viewers. 6126 6127 These parameters can be tweaked: 6128 * Color/Shade of the wireframe. 6129 * Linewidth of the outline frame. 6130 * Cutoff size of windows to not apply wireframing to. 6131 * Cutoffs for closeness to Top, Bottom, Left, and Right edges of 6132 window. 6133 * Modifier keys to enable interior window grabbing. 6134 * Maximum time to wait for dragging pointer events. 6135 * Maximum time to wait for the window to start moving/resizing. 6136 * Maximum time to show a wireframe animation. 6137 * Minimum time between sending wireframe outlines. 6138 6139 See the "-wireframe tweaks" option for more details. On a slow link, 6140 e.g. dialup modem, the parameters may be automatically adjusted for 6141 better response. 6142 6143 6144 CopyRect encoding: In addition to the above there is the 6145 "-wirecopyrect mode" option. It is also on by default. This instructs 6146 x11vnc to not only show the wireframe animation, but to also instruct 6147 all connected VNC viewers to locally translate the window image data 6148 from the original position to the new position on the screen when the 6149 animation is done. This speedup is the VNC CopyRect encoding: the 6150 framebuffer update doesn't need to send the actual new image data. 6151 This is nice in general, and very convenient over a slow link, but 6152 since it is based on heuristics you may need to disable it with the 6153 -nowirecopyrect option (aka -nowcr) if it works incorrectly or 6154 unnaturally for you. 6155 6156 The -wirecopyrect modes are: "never" (same as -nowirecopyrect); "top", 6157 only apply the CopyRect if the window is appears to be on the top of 6158 the window stack and is not obstructed by other windows; and "always" 6159 to always try to apply the CopyRect (obstructed regions are usually 6160 clipped off and not translated.) 6161 6162 Note that some desktops (KDE and xfce) appear to mess with the window 6163 stacking in ways that are not yet clear. In these cases x11vnc works 6164 around the problem by applying the CopyRect even if obscuring windows' 6165 data is translated! Use -nowirecopyrect if this yields undesirable 6166 effects for your desktop. 6167 6168 Also, the CopyRect encoding may give incorrect results under -scale 6169 (depending on the scale factor the CopyRect operation is often only 6170 approximate: the correctly scaled framebuffer will be slightly 6171 different from the translated one.) x11vnc will try to push a 6172 "cleanup" update after the CopyRect if -scale is in effect. Use 6173 -nowirecopyrect if this or other painting errors are unacceptable. 6174 6175 6176 Q-78: Can x11vnc try to apply heuristics to detect when a window is 6177 scrolling its contents and use the CopyRect encoding for a speedup? 6178 6179 Another nice idea for a hack! As of May/2005 x11vnc will by default 6180 apply heuristics to try to detect if the window that has the input 6181 focus is scrolling its contents (but only when x11vnc is feeding user 6182 input, keystroke or pointer, to the X server.) So, when detected, 6183 scrolls induced by dragging on a scrollbar or by typing (e.g. Up or 6184 Down arrows, hitting Return in a terminal window, etc), will show up 6185 much more quickly than via the standard x11vnc screen polling update 6186 mechanism. 6187 6188 There will be a speedup for both slow and fast links to viewers. For 6189 slow links the speedup is mostly due to the CopyRect encoding not 6190 requiring the image data to be transmitted over the network. For fast 6191 links the speedup is primarily due to x11vnc not having to read the 6192 scrolled framebuffer data from the X server (recall that reading from 6193 the hardware framebuffer is slow.) 6194 6195 To do this x11vnc uses the RECORD X extension to snoop the X11 6196 protocol between the X client with the focus window and the X server. 6197 This extension is usually present on most X servers (but SuSE disables 6198 it for some reason.) On XFree86/Xorg it can be enabled via Load 6199 "record" in the Module section of the config file if it isn't already: 6200 Section "Module" 6201 ... 6202 Load "record" 6203 ... 6204 EndSection 6205 6206 Currently the RECORD extension is used as little as possible so as to 6207 not slow down regular use. Only simple heuristics are applied to 6208 detect XCopyArea and XConfigureWindow calls from the application. 6209 These catch a lot of scrolls, e.g. in mozilla/firefox and in terminal 6210 windows like gnome-terminal and xterm. Unfortunately the toolkits KDE 6211 applications use make scroll detection less effective (only rarely are 6212 they detected: i.e. Konqueror and Konsole don't work.) An interesting 6213 project, that may be the direction x11vnc takes, is to record all of 6214 the X11 protocol from all clients and try to "tee" the stream into a 6215 modified Xvfb watching for CopyRect and other VNC speedups. A 6216 potential issue is the RECORD stream is delayed from actual view on 6217 the X server display: if one falls too far behind it could become a 6218 mess... 6219 6220 The initial implementation of -scrollcopyrect option is useful in that 6221 it detects many scrolls and thus gives a much nicer working 6222 environment (especially when combined with the -wireframe 6223 -wirecopyrect options, which are also on by default; and if you are 6224 willing to enable the ShadowFB things are very fast.) The fact that 6225 there aren't long delays or lurches during scrolling is the primary 6226 improvement. 6227 6228 But there are some drawbacks: 6229 * Not all scrolls are detected. Some apps scroll windows in ways 6230 that cannot currently be detected, and other times x11vnc "misses" 6231 the scroll due to timeouts, etc. Sometimes it is more distracting 6232 that a speedup occasionally doesn't work as opposed to being 6233 consistently slow! 6234 * For rapid scrolling (i.e. sequence of many scrolls over a short 6235 period) there can be painting errors (tearing, bunching up, etc.) 6236 during the scroll. These will repair themselves after the scroll 6237 is over, but when they are severe it can be distracting. Try to 6238 think of the approximate window contents as a quicker and more 6239 useful "animation" compared to the slower polling scheme... 6240 * Scrolling inside shells in terminal windows (gnome-terminal, 6241 xterm), can lead to odd painting errors. This is because x11vnc 6242 did not have time to detect a screen change just before the scroll 6243 (most common is the terminal undraws the block cursor before 6244 scrolling the text up: in the viewer you temporarily see multiple 6245 block cursors.) Another issue is with things like more(1): scroll 6246 detection for 5-6 lines happens nicely, but then it can't keep up 6247 and so there is a long pause for the standard polling method to 6248 deliver the remaining updates. 6249 * More rarely sometimes painting errors are not repaired after the 6250 scroll is over. This may be a bug in x11vnc or libvncserver, or it 6251 may be an inescapable fact of the CopyRect encoding and the delay 6252 between RECORD callbacks and what is actually on the X display. 6253 One can tap the Alt_L key (Left "Alt" key) 3 times in a row to 6254 signal x11vnc to refresh the screen to all viewers. Your 6255 VNC-viewer may have its own screen refresh hot-key or button. See 6256 also: -fixscreen 6257 * Some applications, notably OpenOffice, do XCopyArea scrolls in 6258 weird ways that assume ancestor window clipping is taking place. 6259 See the -scr_skip option for ways to tweak this on a 6260 per-application basis. 6261 * Selecting text while dragging the mouse may be slower, especially 6262 if the Button-down event happens near the window's edge. This is 6263 because the scrollcopyrect scheme is watching for scrolls via 6264 RECORD and has to wait for a timeout to occur before it does the 6265 update. 6266 * For reasons not yet understood the RECORD extension can stop 6267 responding (and hence scrolls are missed.) As a workaround x11vnc 6268 attempts to reset the RECORD connection every 60 seconds or so. 6269 Another workaround is to type 4 Super_L (Left Super/Windows-Flag 6270 key) in a row to reset RECORD. Work is in progress to try to fix 6271 this bug. 6272 * Sometimes you need to "retrain" x11vnc for a certain window 6273 because it fails to detect scrolls in it. Sometimes clicking 6274 inside the application window or selecting some text in it to 6275 force the focus helps. 6276 * When using the -scale option there will be a quick CopyRect 6277 scroll, but it needs to be followed by a slower "cleanup" update. 6278 This is because for a fixed finite screen resolution (e.g. 75 dpi) 6279 scaling and copyrect-ing are not exactly independent. Scaling 6280 involves a blending of nearby pixels and if you translate a pixel 6281 the neighbor pixel weighting may be different. So you have to wait 6282 a bit for the cleanup update to finish. On slow links x11vnc may 6283 automatically decide to not detect scrolls when -scale is in 6284 effect. In general it will also try to defer the cleanup update if 6285 possible. 6286 6287 If you find the -scrollcopyrect behavior too approximate or 6288 distracting you can go back to the standard polling-only update method 6289 with the -noscrollcopyrect (or -noscr for short.) If you find some 6290 extremely bad and repeatable behavior for -scrollcopyrect please 6291 report a bug. 6292 6293 Alternatively, as with -wireframe, there are many tuning parameters to 6294 try to improve the situation. You can also access these parameters 6295 inside the gui under "Tuning". These parameters can be tweaked: 6296 * The minimum pixel area of a rectangle to be watched for scrolls. 6297 * A list if application names to skip scroll detection. 6298 * Which keystrokes should trigger scroll detection. 6299 * Which applications should have a "terminal" tweak applied to them. 6300 * When repeating keys (e.g. Up arrow) should be discarded to 6301 preserve a scroll. 6302 * Cutoffs for closeness to Top, Bottom, Left, and Right edges of 6303 window for mouse induced scrolls. 6304 * Set timeout parameters for keystroke induced scrolls. 6305 * Set timeout parameters for mouse pointer induced scrolls. 6306 * Have the full screen be periodically refreshed to fix painting 6307 errors. 6308 6309 6310 Q-79: Can x11vnc do client-side caching of pixel data? I.e. so when 6311 that pixel data is needed again it does not have to be retransmitted 6312 over the network. 6313 6314 As of Dec/2006 in the 0.9 development tarball there is an experimental 6315 client-side caching implementation enabled by the "-ncache n" option. 6316 In fact, during the test period it was on by default with n set to 10. 6317 To disable it use "-noncache". 6318 6319 It is a simple scheme where a (very large) lower portion of the 6320 framebuffer (i.e. starting just below the user's actual desktop 6321 display) is used for storing pixel data. CopyRect; a fast, essentially 6322 local viewer-side VNC encoding; is used to swap the pixel data in and 6323 out of the actual display area. It gives an excellent speedup for 6324 iconifying/deiconifying and moving windows and re-posting of menus 6325 (often it doesn't feel like VNC at all: there is no delay waiting for 6326 the pixel data to fill in.) 6327 6328 This scheme is nice because it does all of this within the existing 6329 VNC protocol, and so it works with all VNC viewers. 6330 6331 A challenge to doing more sophisticated (e.g. compressed and/or 6332 shared) client-side caching is that one needs to extend the VNC 6333 protocol, modify a viewer and then also convince users to adopt your 6334 modified VNC Viewer (or get the new features to be folded into the 6335 main VNC viewers, patches accepted, etc... likely takes many years 6336 before they might be deployed in the field.) So it is convenient that 6337 the "-ncache n" works with any unaltered VNC viewer. 6338 6339 A drawback of the "-ncache n" method is that in the VNC Viewer you can 6340 scroll down and actually see the cached pixel data. So it looks like 6341 there is a bug: you can scroll down in your viewer and see a strange 6342 "history" of windows on your desktop. This is working as intended. One 6343 will need to try to adjust the size of his VNC Viewer window so the 6344 cache area cannot be seen. SSVNC (see below) can do this 6345 automatically. 6346 6347 At some point LibVNCServer may implement a "rfbFBCrop" pseudoencoding 6348 that viewers can use to learn which portion of the framebuffer to 6349 actually show to the users (with the hidden part used for caching, or 6350 perhaps something else, maybe double buffering or other offscreen 6351 rendering...) 6352 6353 The Enhanced TightVNC Viewer (SSVNC) Unix viewer has a nice -ycrop 6354 option to help hide the pixel cache area from view. It will turn on 6355 automatically if the framebuffer appears to be very tall (height more 6356 than twice the width), or you can supply the actual value for the 6357 height. If the screen is resized by scaling, etc, the ycrop value is 6358 scaled as well. In fullscreen mode you cannot scroll past the end of 6359 the actual screen, and in non-fullscreen mode the window manager frame 6360 is adjusted to fit the actual display (so you don't see the pixel 6361 cache region) and the scrollbars are very thin to avoid distraction 6362 and trouble fitting inside your display. Use the "-sbwidth n" viewer 6363 option to make the scrollbars thicker if you like. 6364 6365 Another drawback of the scheme is that it is VERY memory intensive, 6366 the n in "-ncache n" is the factor of increase over the base 6367 framebuffer size to use for caching. It is an even integer and should 6368 be fairly large, 6-12, to achieve good response. This usually requires 6369 about 50-100MB of additional RAM on both the client and server sides. 6370 For example with n=6 a 1280x1024 display will use a framebuffer that 6371 is 1280x7168: everything below row 1024 is the pixel buffer cache. If 6372 you are running on low memory machines or memory is tight because of 6373 other running applications you should not use -ncache. 6374 6375 The reason for so much memory is because the pixel data is not 6376 compressed and so the whole window to be saved must be stored 6377 "offscreen". E.g. for a large web browser window this can be nearly 1 6378 million pixels, and that is only for a single window! One typically 6379 wants to cycle between 5-10 large active windows. Also because both 6380 backing-store (the window's actual contents) and save-unders (the 6381 pixels covered up by the window) are cached offscreen that introduces 6382 an additional factor of 2 in memory use. 6383 6384 However, even in the smallest usage mode with n equal 2 and 6385 -ncache_no_rootpixmap set (this requires only 2X additional 6386 framebuffer memory) there is still a noticable improvement for many 6387 activities, although it is not as dramatic as with, say n equal 12 and 6388 rootpixmap (desktop background) caching enabled. 6389 6390 The large memory consumption of the current implementation can be 6391 thought of as a tradeoff to providing caching and being compatible 6392 with all VNC viewers and also ease of implementing. Hopefully it can 6393 be tuned to use less, or the VNC community will extend the protocol to 6394 allow caching and replaying of compressed blobs of data. 6395 6396 Another option to experiment with is "-ncache_cr". By specifying it, 6397 x11vnc will try to do smooth opaque window moves instead of its 6398 wireframe. This can give a very nice effect (note: on Unix the realvnc 6399 viewer seems to be smoother than the tightvnc viewer), but can lead to 6400 some painting problems, and can be jerky in some circumstances. 6401 6402 Surprisingly, for very slow connections, e.g. modem, the -ncache_cr 6403 option can actually improve window drags. This is probably because no 6404 pixel data (only CopyRect instructions) are sent when dragging a 6405 window. Normally, the wireframe must be sent and this involves 6406 compressing and sending the lines that give rise to the moving box 6407 effect (note that real framebuffer data is sent to "erase" the white 6408 lines of the box.) 6409 6410 If you experience painting errors you can can tap the Alt_L key (Left 6411 "Alt" key) 3 times in a row to signal x11vnc to refresh the screen to 6412 all viewers. You may also need to iconify and then deiconify any 6413 damaged windows to correct their cache data as well. Note that if you 6414 change color viewer depth (e.g. 8bpp to full color) dynamically that 6415 will usually lead to the entire extended framebuffer being resent 6416 which can take a long time over very slow links: it may be better to 6417 reconnect and reset the format right after doing so. x11vnc will try 6418 to detect the format change and clear (make completely black) the 6419 cache region. 6420 6421 Gotcha for older Unix VNC Viewers: The older Unix VNC viewers (e.g. 6422 current TightVNC Unix Viewer) require X server backingstore to keep 6423 off-viewer screen data local. If the viewer-side X server has 6424 backingstore disabled (sadly, currently the default on Linux, etc), 6425 then to get the offscreen pixels the viewer has to ask for a refresh 6426 over the network, thereby defeating the caching. Use something like 6427 this in your viewer-side /etc/X11/xorg.conf file (or otherwise get 6428 your viewer-side system to do it) 6429 Section "Device" 6430 ... 6431 Option "backingstore" 6432 ... 6433 EndSection 6434 6435 No problems like this have been observed with Windows VNC Viewers: 6436 they all seem to keep their entire framebuffer in local memory. 6437 6438 Gotcha for KDE krdc VNC Viewer: One user found that KDE's krdc viewer 6439 has some sort of hardwired limit on the maximum size of the 6440 framebuffer (64MB?). It fails quickly saying "The connection to the 6441 host has been interrupted." The workaround for his 1280x1024 6442 x11vnc-side display was to run with "-ncache 10", i.e. a smaller value 6443 to be under the krdc threshold. 6444 6445 Although this scheme is not as quick (nor as compressed) as 6446 nx/nomachine, say, it does provide a good step in the direction of 6447 improving VNC performance by client side caching. 6448 6449 6450 Q-80: Does x11vnc support TurboVNC? 6451 6452 As of Feb/2009 (development tarball) there is an experimental kludge 6453 to let you build x11vnc using TurboVNC's modified TightVNC encoding. 6454 TurboVNC is part of the VirtualGL project. It does two main things to 6455 speed up the TightVNC encoding: 6456 * It eliminates bottlenecks, overheads, wait-times in the TightVNC 6457 encoding implementation and instead only worries about sending 6458 very well (and quickly) compressed JPEG data. 6459 * A fast proprietary JPEG implemention is used (Intel IPP on x86) 6460 instead of the usual libjpeg implementation. TurboJPEG is an 6461 interface library, libturbojpeg, provided by the project that 6462 achieves this. 6463 6464 TurboVNC works very well over LAN and evidently fast Broadband too. 6465 When using it with x11vnc in such a situation you may want to dial 6466 down the delays, e.g. "-wait 5" and "-defer 5" (or even a smaller 6467 setting) to poll and pump things out more quickly. 6468 6469 See the instructions in "x11vnc/misc/turbovnc/README" for how to build 6470 x11vnc with TurboVNC support. You will also need to download the 6471 TurboJPEG software. 6472 6473 In brief, the steps look like this: 6474 cd x11vnc-x.y.z/x11vnc/misc/turbovnc 6475 ./apply_turbovnc 6476 cd ../../.. 6477 env LDFLAGS='-L/DIR -Xlinker --rpath=/DIR' ./configure 6478 make AM_LDFLAGS='-lturbojpeg' 6479 6480 where you replace "/DIR" with the directory containing libturbojpeg.so 6481 you downloaded separately. If it works out well enough TurboVNC 6482 support will be integrated into x11vnc and more of its tuning features 6483 will be implemented. Support for TurboVNC in SSVNC viewer has been 6484 added as an experiment as well. If you try either one, let us know how 6485 it went. 6486 6487 There also may be some Linux.i686 and Darwin.i386 x11vnc binaries with 6488 TurboVNC support in the misc. bins directory. For other platforms you 6489 will need to compile yourself. 6490 6491 On relatively cheap and old hardware (Althon64 X2 5000+ / GeForce 6492 6200) x11vnc and SSVNC, both TurboVNC enabled, were able to sustain 6493 13.5 frames/sec (fps) and 15 Megapixels/sec using the VirtualGL 6494 supplied OpenGL benchmark program glxspheres. VirtualGL on higher-end 6495 hardware can sustain 20-30 fps with the glxspheres benchmark. 6496 6497 Potential Slowdown: As we describe elsewhere, unless you use x11vnc 6498 with an X server using, say, NVidia proprietary drivers (or a virtual 6499 X server like Xvfb or Xdummy, or in ShadowFB mode), then the read rate 6500 from the graphics card can be rather slow (e.g. 10 MB/sec) and becomes 6501 the bottleneck when using x11vnc over fast networks. Note that all of 6502 Xorg's drivers currently (2009) have slow read rates (only proprietary 6503 drivers appear to have optimized reads.) 6504 6505 So under these (more or less typical) conditions, the speed 6506 improvement provided by TurboVNC may only be marginal. Look for this 6507 output to see your read rate: 6508 28/02/2009 11:11:07 Autoprobing TCP port 6509 28/02/2009 11:11:07 Autoprobing selected port 5900 6510 28/02/2009 11:11:08 fb read rate: 10 MB/sec 6511 28/02/2009 11:11:08 screen setup finished. 6512 6513 A rate of 10 MB/sec means a 1280x1024x24 screen takes 0.5 seconds to 6514 read in. TurboVNC compresses that to JPEG in a much shorter time. On 6515 the other hand, an NVidia driver may have a read rate of 250 MB/sec 6516 and so only takes 0.02 seconds to read the entire screen in. 6517 6518 6519 6520 [Mouse Cursor Shapes] 6521 6522 Q-81: Why isn't the mouse cursor shape (the little icon shape where 6523 the mouse pointer is) correct as I move from window to window? 6524 6525 On X servers supporting XFIXES or Solaris/IRIX Overlay extensions it 6526 is possible for x11vnc to do this correctly. See a few paragraphs down 6527 for the answer. 6528 6529 Historically, the X11 mouse cursor shape (i.e. little picture: an 6530 arrow, X, I-beam, resizer, etc) is one of the few WRITE-only objects 6531 in X11. That is, an application can tell the X server what the cursor 6532 shape should be when the pointer is in a given window, but a program 6533 (like x11vnc) unfortunately cannot read this information. I believe 6534 this is because the cursor shape is often downloaded to the graphics 6535 hardware (video card), but I could be mistaken. 6536 6537 A simple kludge is provided by the "-cursor X" option that changes the 6538 cursor when the mouse is on the root background (or any window has the 6539 same cursor as the root background.) Note that desktops like GNOME or 6540 KDE often cover up the root background, so this won't work for those 6541 cases. Also see the "-cursor some" option for additional kludges. 6542 6543 Note that as of Aug/2004 on Solaris using the SUN_OVL overlay 6544 extension and IRIX, x11vnc can show the correct mouse cursor when the 6545 -overlay option is supplied. See this FAQ for more info. 6546 6547 Also as of Dec/2004 XFIXES X extension support has been added to allow 6548 exact extraction of the mouse cursor shape. XFIXES fixes the problem 6549 of the cursor-shape being write-only: x11vnc can now query the X 6550 server for the current shape and send it back to the connected 6551 viewers. XFIXES is available on recent Linux Xorg based distros and 6552 Solaris 10. 6553 6554 The only XFIXES issue is the handling of alpha channel transparency in 6555 cursors. If a cursor has any translucency then in general it must be 6556 approximated to opaque RGB values for use in VNC. There are some 6557 situations where the cursor transparency can also handled exactly: 6558 when the VNC Viewer requires the cursor shape be drawn into the VNC 6559 framebuffer or if you apply a patch to your VNC Viewer to extract 6560 hidden alpha channel data under 32bpp. Details can be found here. 6561 6562 6563 Q-82: When using XFIXES cursorshape mode, some of the cursors look 6564 really bad with extra black borders around the cursor and other cruft. 6565 How can I improve their appearance? 6566 6567 This happens for cursors with transparency ("alpha channel"); regular 6568 X cursors (bitmaps) should be correct. Unfortunately x11vnc 0.7 was 6569 released with a very poor algorithm for approximating the 6570 transparency, which led to the ugly black borders. 6571 6572 The problem is as follows: XFIXES allows x11vnc to retrieve the 6573 current X server cursor shape, including the alpha channel for 6574 transparency. For traditional bitmap cursors the alpha value will be 0 6575 for completely transparent pixels and 255 for completely opaque 6576 pixels; whereas for modern, eye-candy cursors an alpha value between 0 6577 and 255 means to blend in the background colors to that degree with 6578 the cursor colors. The pixel color blending formula is something like 6579 this: Red = Red_cursor * a + Red_background * (1 - a), (where here 0 6580 =< a =< 1), with similar for Green and Blue. The VNC protocol does not 6581 currently support an alpha channel in cursors: it only supports 6582 regular X bitmap cursors and Rich Cursors that have RGB (Red, Green, 6583 Blue) color data, but no "A" = alpha data. So in general x11vnc has to 6584 approximate a cursor with transparency to create a Rich Cursor. This 6585 is easier said than done: some cursor themes have cursors with 6586 complicated drop shadows and other forms of translucency. 6587 6588 Anyway, for the x11vnc 0.7.1 release the algorithm for approximating 6589 transparency is much improved and hopefully gives decent cursor shapes 6590 for most cursor themes and you don't have to worry about it. 6591 6592 In case it still looks bad for your cursor theme, there are (of 6593 course!) some tunable parameters. The "-alphacut n" option lets you 6594 set the threshold "n" (between 0 and 255): cursor pixels with alpha 6595 values below n will be considered completely transparent while values 6596 equal to or above n will be completely opaque. The default is 240. The 6597 "-alphafrac f" option tries to correct individual cursors that did not 6598 fare well with the default -alphacut value: if a cursor has less than 6599 fraction f (between 0.0 and 1.0) of its pixels selected by the default 6600 -alphacut, the threshold is lowered until f of its pixels are 6601 selected. The default fraction is 0.33. 6602 6603 Finally, there is an option -alpharemove that is useful for themes 6604 where many cursors are light colored (e.g. "whiteglass".) XFIXES 6605 returns the cursor data with the RGB values pre-multiplied by the 6606 alpha value. If the white cursors look too grey, specify -alpharemove 6607 to brighten them by having x11vnc divide out the alpha value. 6608 6609 One user played with these parameters and reported back: 6610 Of the cursor themes present on my system: 6611 6612 gentoo and gentoo-blue: alphacut:192 - noalpharemove 6613 6614 gentoo-silver: alphacut:127 and alpharemove 6615 6616 whiteglass and redglass (presumably also handhelds, which is based 6617 heavily on redglass) look fine with the apparent default of alphacut:255. 6618 6619 6620 Q-83: In XFIXES mode, are there any hacks to handle cursor 6621 transparency ("alpha channel") exactly? 6622 6623 As of Jan/2005 libvncserver has been modified to allow an alpha 6624 channel (i.e. RGBA data) for Rich Cursors. So x11vnc can now send the 6625 alpha channel data to libvncserver. However, this data will only be 6626 used for VNC clients that do not support the CursorShapeUpdates VNC 6627 extension (or have disabled it.) It can be disabled for all clients 6628 with the -nocursorshape x11vnc option. In this case the cursor is 6629 drawn, correctly blended with the background, into the VNC framebuffer 6630 before being sent out to the client. So the alpha blending is done on 6631 the x11vnc side. Use the -noalphablend option to disable this behavior 6632 (always approximate transparent cursors with opaque RGB values.) 6633 6634 The CursorShapeUpdates VNC extension complicates matters because the 6635 cursor shape is sent to the VNC viewers supporting it, and the viewers 6636 draw the cursor locally. This improves response over slow links. Alpha 6637 channel data for these locally drawn cursors is not supported by the 6638 VNC protocol. 6639 6640 However, in the libvncserver CVS there is a patch to the TightVNC 6641 viewer to make this work for CursorShapeUpdates under some 6642 circumstances. This hack is outside of the VNC protocol. It requires 6643 the screens on both sides to be depth 24 at 32bpp (it uses the extra 8 6644 bits to secretly hide the cursor alpha channel data.) Not only does it 6645 require depth 24 at 32bpp, but it also currently requires the client 6646 and server to be of the same endianness (otherwise the hidden alpha 6647 data gets reset to zero by a libvncserver translation function; we can 6648 fix this at some point if there is interest.) The patch is for the 6649 TightVNC 1.3dev5 Unix vncviewer and it enables the TightVNC viewer to 6650 do the cursor alpha blending locally. The patch code should give an 6651 example on how to change the Windows TightVNC viewer to achieve the 6652 same thing (send me the patch if you get that working.) 6653 6654 This patch is applied to the Enhanced TightVNC Viewer (SSVNC) package 6655 we provide. 6656 6657 [Mouse Pointer] 6658 6659 Q-84: Why does the mouse arrow just stay in one corner in my 6660 vncviewer, whereas my cursor (that does move) is just a dot? 6661 6662 This default takes advantage of a tightvnc extension 6663 (CursorShapeUpdates) that allows specifying a cursor image shape for 6664 the local VNC viewer. You may disable it with the -nocursor option to 6665 x11vnc if your viewer does not have this extension. 6666 6667 Note: as of Aug/2004 this should be fixed: the default for 6668 non-tightvnc viewers (or ones that do not support CursorShapeUpdates) 6669 will be to draw the moving cursor into the x11vnc framebuffer. This 6670 can also be disabled via -nocursor. 6671 6672 6673 Q-85: Can I take advantage of the TightVNC extension to the VNC 6674 protocol where Cursor Positions Updates are sent back to all connected 6675 clients (i.e. passive viewers can see the mouse cursor being moved 6676 around by another viewer)? 6677 6678 Use the -cursorpos option when starting x11vnc. A VNC viewer must 6679 support the Cursor Positions Updates for the user to see the mouse 6680 motions (the TightVNC viewers support this.) As of Aug/2004 -cursorpos 6681 is the default. See also -nocursorpos and -nocursorshape. 6682 6683 6684 Q-86: Is it possible to swap the mouse buttons (e.g. left-handed 6685 operation), or arbitrarily remap them? How about mapping button clicks 6686 to keystrokes, e.g. to partially emulate Mouse wheel scrolling? 6687 6688 You can remap the mouse buttons via something like: -buttonmap 13-31 6689 (or perhaps 12-21.) Also, note that xmodmap(1) lets you directly 6690 adjust the X server's button mappings, but in some circumstances it 6691 might be more desirable to have x11vnc do it. 6692 6693 One user had an X server with only one mouse button(!) and was able to 6694 map all of the VNC client mouse buttons to it via: -buttonmap 123-111. 6695 6696 Note that the -debug_pointer option prints out much info for every 6697 mouse/pointer event and is handy in solving problems. 6698 6699 To map mouse button clicks to keystrokes you can use the alternate 6700 format where the keystrokes are enclosed between colons like this 6701 :<KeySym>: in place of the mouse button digit. For a sequence of 6702 keysyms separate them with "+" signs. Look in the include file 6703 <X11/keysymdef.h>, or use xev(1), or -debug_keyboard to find the 6704 keysym names. Button clicks can also be included in the sequence via 6705 the fake keysyms Button1, etc. 6706 6707 As an example, suppose the VNC viewer machine has a mouse wheel (these 6708 generate button 4 and 5 events), but the machine that x11vnc is run on 6709 only has the 3 regular buttons. In normal operation x11vnc will 6710 discard the button 4 and 5 events. However, either of the following 6711 button maps could possibly be of use emulating the mouse wheel events 6712 in this case: 6713 -buttonmap 12345-123:Prior::Next: 6714 -buttonmap 12345-123:Up+Up+Up::Down+Down+Down: 6715 6716 Exactly what keystroke "scrolling" events they should be bound to 6717 depends on one's taste. If this method is too approximate, one could 6718 consider not using -buttonmap but rather configuring the X server to 6719 think it has a mouse with 5 buttons even though the physical mouse 6720 does not. (e.g. 'Option "ZAxisMapping" "4 5"'.) 6721 6722 Note that when a keysym-mapped mouse button is clicked down this 6723 immediately generates the key-press and key-release events (for each 6724 keysym in turn if the mapping has a sequence of keysyms.) When the 6725 mouse button goes back up nothing is generated. 6726 6727 If you include modifier keys like Shift_L instead of key-press 6728 immediately followed by key-release the state of the modifier key is 6729 toggled (however the initial state of the modifier key is ignored.) So 6730 to map the right button to type my name 'Karl Runge' I could use this: 6731 -buttonmap 3-:Shift_L+k+Shift_L+a+r+l+space+Shift_L+r+Shift_L+u+n+g+e: 6732 6733 (yes, this is getting a little silly.) 6734 6735 BTW, Coming the other way around, if the machine you are sitting at 6736 does not have a mouse wheel, but the remote machine does (or at least 6737 has 5 buttons configured), this key remapping can be useful: 6738 -remap Super_R-Button4,Menu-Button5 6739 6740 you just tap those two keys to get the mouse wheel scrolls (this is 6741 more useful than the Up and Down arrow keys because a mouse wheel 6742 "click" usually gives a multi-line scroll.) 6743 [Keyboard Issues] 6744 6745 Q-87: How can I get my AltGr and Shift modifiers to work between 6746 keyboards for different languages? 6747 6748 The option -modtweak should help here. It is a mode that monitors the 6749 state of the Shift and AltGr Modifiers and tries to deduce the correct 6750 keycode to send, possibly by sending fake modifier key presses and 6751 releases in addition to the actual keystroke. 6752 6753 Update: As of Jul/2004 -modtweak is now the default (use -nomodtweak 6754 to get the old behavior.) This was done because it was noticed on 6755 newer XFree86 setups even on bland "us" keyboards like "pc104 us" 6756 XFree86 included a "ghost" key with both "<" and ">" it. This key does 6757 not exist on the keyboard (see this FAQ for more info.) Without 6758 -modtweak there was then an ambiguity in the reverse map keysym => 6759 keycode, making it so the "<" symbol could not be typed. 6760 6761 Also see the FAQ about the -xkb option for a more powerful method of 6762 modifier tweaking for use on X servers with the XKEYBOARD extension. 6763 6764 When trying to resolve keyboard mapping problems, note that the 6765 -debug_keyboard option prints out much info for every keystroke and so 6766 can be useful debugging things. 6767 6768 Note that one user had a strange setup and none of the above helped. 6769 His solution was to disable all of the above and use -nomodtweak. This 6770 is the simplest form of keystroke insertion and it actually solved the 6771 problem. Try it if the other options don't help. 6772 6773 6774 Q-88: When I try to type a "<" (i.e. less than) instead I get ">" 6775 (i.e. greater than)! Strangely, typing ">" works OK!! 6776 6777 Does your keyboard have a single key with both "<" and ">" on it? Even 6778 if it doesn't, your X server may think your keyboard has such a key 6779 (e.g. pc105 in the XF86Config file when it should be something else, 6780 say pc104.) 6781 6782 Short Cut: Try the -xkb or -sloppy_keys options and see if that helps 6783 the situation. The discussion below is a bit outdated (e.g. -modtweak 6784 is now the default) but it is useful reference for various tricks and 6785 so is kept. 6786 6787 6788 The problem here is that on the Xserver where x11vnc is run there are 6789 two keycodes that correspond to the "<" keysym. Run something like 6790 this to see: 6791 6792 xmodmap -pk | egrep -i 'KeyCode|less|greater' 6793 There are 4 KeySyms per KeyCode; KeyCodes range from 8 to 255. 6794 KeyCode Keysym (Keysym) ... 6795 59 0x002c (comma) 0x003c (less) 6796 60 0x002e (period) 0x003e (greater) 6797 94 0x003c (less) 0x003e (greater) 6798 6799 That keycode 94 is the special key with both "<" and ">". When x11vnc 6800 receives the "<" keysym over the wire from the remote VNC client, it 6801 unfortunately maps it to keycode 94 instead of 59, and sends 94 to the 6802 X server. Since Shift is down (i.e. you are Shifting the comma key), 6803 the X server interprets this as Shifted-94, which is ">". 6804 6805 A workaround in the X server configuration is to "deaden" that special 6806 key: 6807 6808 xmodmap -e "keycode 94 = " 6809 6810 However, one user said he had to do this: 6811 6812 xmodmap -e "keycode 94 = 0x002c 0x003c" 6813 6814 (If the numerical values are different for your setup, substitute the 6815 ones that correspond to your display. The above xmodmap scheme can 6816 often be used to work around other ambiguous keysym to keycode 6817 mappings.) 6818 6819 Alternatively, here are some x11vnc options to try to work around the 6820 problem: 6821 -modtweak 6822 6823 and 6824 -remap less-comma 6825 6826 These are convenient in that they do not modify the actual X server 6827 settings. The former (-modtweak) is a mode that monitors the state of 6828 the Shift and AltGr modifiers and tries to deduce the correct keycode 6829 sequence to send. Since Jul/2004 -modtweak is now the default. The 6830 latter (-remap less-comma) is an immediate remapping of the keysym 6831 less to the keysym comma when it comes in from a client (so when Shift 6832 is down the comma press will yield "<".) 6833 6834 See also the FAQ about the -xkb option as a possible workaround using 6835 the XKEYBOARD extension. 6836 6837 Note that the -debug_keyboard option prints out much info for every 6838 keystroke to aid debugging keyboard problems. 6839 6840 6841 Q-89: Extra Character Inserted, E.g.: When I try to type a "<" (i.e. 6842 less than) instead I get "<," (i.e. an extra comma.) 6843 6844 This is likely because you press "Shift" then "<" but then released 6845 the Shift key before releasing the "<". Because of a keymapping 6846 ambiguity the last event "< up" is interpreted as "," because that key 6847 unshifted is the comma. 6848 6849 This extra character insertion will happen for other combinations of 6850 characters: in general it can happen whenever the Shift key is 6851 released early. 6852 6853 This should not happen in -xkb mode, because it works hard to resolve 6854 the ambiguities. If you do not want to use -xkb, try the option 6855 -sloppy_keys to attempt a similar type of algorithm. 6856 6857 One user had this problem for Italian and German keyboards with the 6858 key containing ":" and "." When he typed ":" he would get an extra "." 6859 inserted after the ":". The solution was -sloppy_keys. 6860 6861 6862 Q-90: I'm using an "international" keyboard (e.g. German "de", or 6863 Danish "dk") and the -modtweak mode works well if the VNC viewer is 6864 run on a Unix/Linux machine with a similar keyboard. But if I run 6865 the VNC viewer on Unix/Linux with a different keyboard (e.g. "us") or 6866 Windows with any keyboard, I can't type some keys like: "@", "$", 6867 "<", ">", etc. How can I fix this? 6868 6869 The problem with Windows is it does not seem to handle AltGr well. It 6870 seems to fake it up by sending Control_L+Alt_R to applications. The 6871 Windows VNC viewer sends those two down keystrokes out on the wire to 6872 the VNC server, but when the user types the next key to get, e.g., "@" 6873 the Windows VNC viewer sends events bringing the up the 6874 Control_L+Alt_R keys, and then sends the "@" keysym by itself. 6875 6876 The Unix/Linux VNC viewer on a "us" keyboard does a similar thing 6877 since "@" is the Shift of the "2" key. The keysyms Shift and "@" are 6878 sent to the VNC server. 6879 6880 In both cases no AltGr is sent to the VNC server, but we know AltGr is 6881 needed on the physical international keyboard to type a "@". 6882 6883 This all worked fine with x11vnc running with the -modtweak option (it 6884 figures out how to adjust the Modifier keys (Shift or AltGr) to get 6885 the "@".) However it fails under recent versions of XFree86 (and the 6886 X.org fork.) These run the XKEYBOARD extension by default and make 6887 heavy use of it to handle international keyboards. 6888 6889 To make a long story short, on these newer XFree86 setups the 6890 traditional X keymap lookup x11vnc uses is no longer accurate. x11vnc 6891 can't find the keysym "@" anywhere in the keymapping! (even though it 6892 is in the XKEYBOARD extended keymapping.) 6893 6894 How to Solve: As of Jul/2004 x11vnc has two changes: 6895 * -modtweak (tweak Modifier keys) is now the default (use 6896 -nomodtweak to go back to the old way) 6897 * there is a new option -xkb to use the XKEYBOARD extension API to 6898 do the Modifier key tweaking. 6899 6900 The -xkb option seems to fix all of the missing keys: "@", "<", ">", 6901 etc.: it is recommended that you try it if you have this sort of 6902 problem. Let us know if there are any remaining problems (see the next 6903 paragraph for some known problems.) If you specify the -debug_keyboard 6904 (aka -dk) option twice you will get a huge amount of keystroke 6905 debugging output (send it along with any problems you report.) 6906 6907 Update: as of Jun/2005 x11vnc will try to automatically enable -xkb if 6908 it appears that would be beneficial (e.g. if it sees any of "@", "<", 6909 ">", "[" and similar keys are mapped in a way that needs the -xkb to 6910 access them.) To disable this automatic check use -noxkb. 6911 6912 Known problems: 6913 * One user had to disable a "ghost" Mode_switch key that was causing 6914 problems under -xkb. His physical AltGr key was bound to 6915 ISO_Level3_Shift (which seems to be the XKEYBOARD way of doing 6916 things), while there was a ghost key Mode_switch (which seems to 6917 be obsolete) in the mapping as well. Both of these keysyms were 6918 bound to Mod5 and x11vnc was unfortunately choosing Mode_switch. 6919 From the x11vnc -xkb -dk -dk output it was noted that Mode_switch 6920 was attached to keycode 93 (no physical key generates this 6921 keycode) while ISO_Level3_Shift was attached to keycode 113. The 6922 keycode skipping option was used to disable the ghost key: 6923 -skip_keycodes 93 6924 * In implementing -xkb we noticed that some characters were still 6925 not getting through, e.g. "~" and "^". This is not really an 6926 XKEYBOARD problem. What was happening was the VNC viewer was 6927 sending the keysyms asciitilde and asciicircum to x11vnc, but on 6928 the X server with the international keyboard those keysyms were 6929 not mapped to any keys. So x11vnc had to skip them (Note: as of 6930 May/2005 they are added by default see -add_keysyms below.) 6931 The way these characters are typically entered on international 6932 keyboards is by "dead" (aka "mute") keys. E.g. to enter "~" at the 6933 physical display the keysym dead_tilde is pressed and released 6934 (this usually involves holding AltGr down while another key is 6935 pressed) and then space is pressed. (this can also be used get 6936 characters with the "~" symbol on top, e.g. "" by typing "a" 6937 instead of space.) 6938 What to do? In general the VNC protocol has not really solved this 6939 problem: what should be done if the VNC viewer sends a keysym not 6940 recognized by the VNC server side? Workarounds can possibly be 6941 created using the -remap x11vnc option: 6942 -remap asciitilde-dead_tilde,asciicircum-dead_circumflex 6943 etc. Use -remap filename if the list is long. Please send us your 6944 workarounds for this problem on your keyboard. Perhaps we can have 6945 x11vnc adjust automatically at some point. Also see the 6946 -add_keysyms option in the next paragraph. 6947 Update: for convenience "-remap DEAD" does many of these mappings 6948 at once. 6949 * To complement the above workaround using the -remap, an option 6950 -add_keysyms was added. This option instructs x11vnc to bind any 6951 unknown Keysyms coming in from VNC viewers to unused Keycodes in 6952 the X server. This modifies the global state of the X server. When 6953 x11vnc exits it removes the extra keymappings it created. Note 6954 that the -remap mappings are applied first, right when the Keysym 6955 is received from a VNC viewer, and only after that would 6956 -add_keysyms, or anything else, come into play. 6957 Update: -add_keysyms is now on by default. Use -noadd_keysyms to 6958 disable. 6959 6960 6961 Q-91: When typing I sometimes get double, triple, or more of my 6962 keystrokes repeated. I'm sure I only typed them once, what can I do? 6963 6964 This may be due to an interplay between your X server's key autorepeat 6965 delay and the extra time delays caused by x11vnc processing. 6966 6967 Short answer: disable key autorepeating by running the command "xset r 6968 off" on the Xserver where x11vnc is run (restore via "xset r on") or 6969 use the new (Jul/2004) -norepeat x11vnc option. You will still have 6970 autorepeating because that is taken care of on your VNC viewer side. 6971 6972 Update: as of Dec/2004 -norepeat is now the default. Use -repeat to 6973 disable it. 6974 6975 Details: 6976 suppose you press a key DOWN and it generates changes in large regions 6977 of the screen. The CPU and I/O work x11vnc does for the large screen 6978 change could be longer than your X server's key autorepeat delay. 6979 x11vnc may not get to processing the key UP event until after the 6980 screen work is completed. The X server believes the key has been held 6981 down all this time, and applies its autorepeat rules. 6982 6983 Even without inducing changes in large regions of the screen, this 6984 problem could arise when accessing x11vnc via a dialup modem or 6985 otherwise high latency link (e.g. > 250 ms latency.) 6986 6987 Look at the output of "xset q" for the "auto repeat delay" setting. Is 6988 it low (e.g. < 300 ms)? If you turn off autorepeat completely: "xset r 6989 off", does the problem go away? 6990 6991 The workaround is to manually apply "xset r off" and "xset r on" as 6992 needed, or to use the -norepeat (which has since Dec/2004 been made 6993 the default.) Note that with X server autorepeat turned off the VNC 6994 viewer side of the connection will (nearly always) do its own 6995 autorepeating so there is no big loss here, unless someone is also 6996 working at the physical display and misses his autorepeating. 6997 6998 6999 Q-92: The x11vnc -norepeat mode is in effect, but I still get repeated 7000 keystrokes!! 7001 7002 Are you using x11vnc to log in to an X session via display manager? 7003 (as described in this FAQ) If so, x11vnc is starting before your 7004 session and it disables autorepeat when you connect, but then after 7005 you log in your session startup (GNOME, KDE, ...) could be resetting 7006 the autorepeat to be on. Or it could be something inside your desktop 7007 trying to be helpful that decides to turn it back on. 7008 7009 x11vnc in -norepeat mode will by default reset autorepeat to off 2 7010 times (to help get thru the session startup problem), but it will not 7011 continue to battle with things turning autorepeat back on. It will 7012 also turn autorepeat off whenever it goes from a state of zero clients 7013 to one client. You can adjust the number of resets via "-norepeat N", 7014 or use "-norepeat -1" to have it keep resetting it whenever autorepeat 7015 gets turned back on when clients are connected. 7016 7017 In general you can manually turn autorepeating off by typing "xset r 7018 off", or a using desktop utility/menu, or "x11vnc -R norepeat". If 7019 something in your desktop is automatically turning it back on you 7020 should figure out how to disable that somehow. 7021 7022 7023 Q-93: After using x11vnc for a while, I find that I cannot type some 7024 (or any) characters or my mouse clicks and drags no longer have any 7025 effect, or they lead to strange effects. What happened? 7026 7027 Probably a modifier key, e.g. Control or Alt is "stuck" in a pressed 7028 down state. 7029 7030 This happens for VNC in general by the following mechanism. Suppose on 7031 the Viewer side desktop there is some hot-key to switch 7032 desktops/rooms/spaces, etc. E.g. suppose Alt+LeftArrow moves to the 7033 left desktop/room/space. Or suppose an Alt+hotkey combination 7034 iconifies a window. This can leave the Alt key pressed down on the 7035 remote side. 7036 7037 Consider the sequence that happens. The Alt_L key and then the 7038 LeftArrow key go down. Since you are inside the viewer the Alt_L key 7039 press is sent to the other side (x11vnc) and so it is pressed down in 7040 the remote desktop as well. (by "Alt_L" we mean the Alt key on the 7041 left-hand side of the keyboard.) Your local desktop (where the VNC 7042 Viewer is running) then warps to the new desktop/room/space: Leaving 7043 the Alt_L key still pressed down in the remote desktop. 7044 7045 If someone is sitting at the desktop, or when you return in the viewer 7046 it may be very confusing because the Alt_L is still pressed down but 7047 you (or the person sitting at the desktop) do not realize this. 7048 Depending on which remote desktop (x11vnc side) is used, it can act 7049 very strangely. 7050 7051 A quick workaround when you notice this is to press and release all of 7052 the Alt, Shift, Control, Windows-Flag, modifier keys to free the 7053 pressed one. You need to do this for both the left and right Shift, 7054 Alt, Control, etc. keys to be sure. 7055 7056 Note that many VNC Viewers try to guard against this when they are 7057 notified by the window system that the viewer app has "lost focus". 7058 When it receives the "lost focus" event, the viewer sends VNC 7059 Key-Release events for all modifier keys that are currently pressed 7060 down. This does not always work, however, since it depends on how the 7061 desktop manages these "warps". If the viewer is not notified it cannot 7062 know it needs to release the modifiers. 7063 7064 You can also use the -clear_mods option to try to clear all of the 7065 modifier keys at x11vnc startup. You will still have to be careful 7066 that you do not leave the modifier key pressed down during your 7067 session. It is difficult to prevent this problem from occurring (short 7068 of using -remap to prevent sending all of the problem modifier keys, 7069 which would make the destkop pretty unusable.) 7070 7071 During a session these x11vnc remote control commands can also help: 7072 x11vnc -R clear_mods 7073 x11vnc -R clear_keys 7074 x11vnc -R clear_locks 7075 x11vnc -R clear_all 7076 7077 A similar problem can occur if you accidentally press the Caps_Lock or 7078 Num_Lock down. When these are locked on the remote side it can 7079 sometimes lead to strange desktop behavior (e.g. cannot drag or click 7080 on windows.) As above you may not notice this because the lock isn't 7081 down on the local (Viewer) side. See this FAQ on lock keys problem. 7082 These options may help avoid the problem: -skip_lockkeys and 7083 -capslock. See also -clear_all. 7084 7085 7086 Q-94: The machine where I run x11vnc has an AltGr key, but the local 7087 machine where I run the VNC viewer does not. Is there a way I can map 7088 a local unused key to send an AltGr? How about a Compose key as well? 7089 7090 Something like "-remap Super_R-Mode_switch" x11vnc option may work. 7091 Note that Super_R is the "Right Windoze(tm) Flaggie" key; you may want 7092 to choose another. The -debug_keyboard option comes in handy in 7093 finding keysym names (so does xev(1).) 7094 7095 For Compose how about "-remap Menu-Multi_key" (note that Multi_key is 7096 the official name for Compose.) To do both at the same time: "-remap 7097 Super_R-Mode_switch,Menu-Multi_key" or use "-remap filename" to 7098 specify remappings from a file. 7099 7100 7101 Q-95: I have a Sun machine I run x11vnc on. Its Sun keyboard has just 7102 one Alt key labelled "Alt" and two Meta keys labelled with little 7103 diamonds. The machine where I run the VNC viewer only has Alt keys. 7104 How can I send a Meta keypress? (e.g. emacs needs this) 7105 7106 Here are a couple ideas. The first one is to simply use xmodmap(1) to 7107 adjust the Sun X server. Perhaps xmodmap -e "keysym Alt_L = Meta_L 7108 Alt_L" will do the trick. (there are other ways to do it, one user 7109 used: xmodmap -e "keycode 26 = Meta_L" for his setup.) 7110 7111 Since xmodmap(1) modifies the X server mappings you may not want to do 7112 this (because it affects local work on that machine.) Something like 7113 the -remap Alt_L-Meta_L to x11vnc may be sufficient for ones needs, 7114 and does not modify the X server environment. Note that you cannot 7115 send Alt_L in this case, maybe -remap Super_L-Meta_L would be a better 7116 choice if the Super_L key is typically unused in Unix. 7117 7118 7119 Q-96: Running x11vnc on HP-UX I cannot type "#" I just get a "3" 7120 instead. 7121 7122 One user reports this problem on HP-UX Rel_B.11.23. The problem was 7123 traced to a strange keyboard mapping for the machine (e.g. xmodmap -pk 7124 output) that looked like: 7125 ... 7126 039 2 at at at 7127 ... 7128 047 3 numbersign numbersign numbersign 7129 7130 and similar triple mappings (with two in the AltGr/Mode_switch group) 7131 of a keysum to a single keycode. 7132 7133 Use the -nomodtweak option as a workaround. You can also use xmodmap 7134 to correct these mappings in the server, e.g.: 7135 xmodmap -e "keycode 47 = 3 numbersign" 7136 7137 Also, as of Feb/2007, set the environment variable MODTWEAK_LOWEST=1 7138 (either in your shell or via "-env MODTWEAK_LOWEST=1" option) to 7139 handle these mappings better. 7140 7141 7142 Q-97: Can I map a keystroke to a mouse button click on the remote 7143 machine? 7144 7145 This can be done directly in some X servers using AccessX and 7146 Pointer_EnableKeys, but is a bit awkward. It may be more convenient to 7147 have x11vnc do the remapping. This can be done via the -remap option 7148 using the fake "keysyms" Button1, Button2, etc. as the "to" keys (i.e. 7149 the ones after the "-") 7150 7151 As an example, consider a laptop where the VNC viewer is run that has 7152 a touchpad with only two buttons. It is difficult to do a middle 7153 button "paste" because (using XFree86/Xorg Emulate3Buttons) you have 7154 to click both buttons on the touch pad at the same time. This 7155 remapping: 7156 -remap Super_R-Button2 7157 7158 maps the Super_R "flag" key press to the Button2 click, thereby making 7159 X pasting a bit easier. 7160 7161 Note that once the key goes down, the button down and button up events 7162 are generated immediately on the x11vnc side. When the key is released 7163 (i.e. goes up) no events are generated. 7164 7165 Q-98: How can I get Caps_Lock to work between my VNC viewer and 7166 x11vnc? 7167 7168 This is a little tricky because it is possible to get the Caps_Lock 7169 state out of sync between your viewer-side machine and the x11vnc-side 7170 X server. For best results, we recommend not ever letting the 7171 Caps_Lock keypresses be processed by x11vnc. That way when you press 7172 Caps_Lock in the viewer your local machine goes into the Caps_Lock on 7173 state and sends keysym "A" say when you press "a". x11vnc will then 7174 fake things up so that Shift is held down to generate "A". The 7175 -skip_lockkeys option should help to accomplish this. For finer grain 7176 control use something like: "-remap Caps_Lock-None". 7177 7178 Also try the -nomodtweak and -capslock options. 7179 7180 Another useful option that turns off any Lock keys on the remote side 7181 at startup and end is the -clear_all option. During a session you can 7182 run these remote control commands to modify the Lock keys: 7183 x11vnc -R clear_locks 7184 x11vnc -R clear_all 7185 7186 the former will try to unset any Lock keys, the latter will do same 7187 and also try to make it so no key is pressed down (e.g. "stuck" Alt_L, 7188 etc.) 7189 [Screen Related Issues and Features] 7190 7191 Q-99: The remote display is larger (in number of pixels) than the 7192 local display I am running the vncviewer on. I don't like the 7193 vncviewer scrollbars, what I can do? 7194 7195 vncviewer has a option (usually accessible via F8 key or -fullscreen 7196 option) for vncviewer to run in full screen, where it will 7197 automatically scroll when the mouse is near the edge of the current 7198 view. For quick scrolling, also make sure Backing Store is enabled on 7199 the machine vncviewer is run on. (XFree86/Xorg disables it by default 7200 for some reason, add Option "backingstore" to XF86Config on the 7201 vncviewer side.) 7202 7203 BTW, contact me if you are having problems with vncviewer in 7204 fullscreen mode with your window manager (i.e. no keyboard response.) 7205 I have a workaround for vncviewer using XGrabServer(). 7206 7207 There may also be scaling viewers out there (e.g. TightVNC or UltraVNC 7208 on Windows) that automatically shrink or expand the remote framebuffer 7209 to fit the local display. Especially for hand-held devices. See also 7210 the next FAQ on x11vnc scaling. 7211 7212 7213 Q-100: Does x11vnc support server-side framebuffer scaling? (E.g. to 7214 make the desktop smaller.) 7215 7216 As of Jun/2004 x11vnc provides basic server-side scaling. It is a 7217 global scaling of the desktop, not a per-client setting. To enable it 7218 use the "-scale fraction" option. "fraction" can either be a floating 7219 point number (e.g. -scale 0.75) or the alternative m/n fraction 7220 notation (e.g. -scale 3/4.) Note that if fraction is greater than one 7221 the display is magnified. 7222 7223 Extra resources (CPU, memory I/O, and memory) are required to do the 7224 scaling. If the machine is slow where x11vnc is run with scaling 7225 enabled, the interactive response can be unacceptable. OTOH, if run 7226 with scaling on a fast machine the performance degradation is usually 7227 not a big issue or even noticeable. 7228 7229 It may help to compile x11vnc with compiler option -O3 or -O4 to speed 7230 up the scaling code. Set the CFLAGS env. var. before running 7231 configure. 7232 7233 Also, if you just want a quick, rough "thumbnail" of the display you 7234 can append ":nb" to the fraction to turn on "no blending" mode. E.g.: 7235 "-scale 1/3:nb" Fonts will be difficult to read, but the larger 7236 features will be recognizable. BTW, "no blending" mode is forced on 7237 when scaling 8bpp PseudoColor displays (because blending an indexed 7238 colormap is a bad idea and leads to random colors, use :fb to force it 7239 on.) 7240 7241 One can also use the ":nb" with an integer scale factor (say "-scale 7242 2:nb") to use x11vnc as a screen magnifier for vision impaired 7243 applications. Since with integer scale factors the framebuffers become 7244 huge and scaling operations time consuming, be sure to use ":nb" for 7245 the fastest response. 7246 7247 In general for a scaled display if you are using a TightVNC viewer you 7248 may want to turn off jpeg encoding (e.g. vncviewer -nojpeg host:0.) 7249 There appears to be a noise enhancement effect, especially for regions 7250 containing font/text: the scaling can introduce some pixel artifacts 7251 that evidently causes the tight encoding algorithm to incorrectly 7252 detect the regions as image data and thereby introduce additional 7253 pixel artifacts due to the lossiness of the jpeg compression 7254 algorithm. Experiment to see if -nojpeg vncviewer option improves the 7255 readability of text when using -scale to shrink the display size. Also 7256 note that scaling may actually slow down the transfer of text regions 7257 because after being scaled they do not compress as well. (this can 7258 often be a significant slowdown, e.g. 10X.) 7259 7260 Another issue is that it appears VNC viewers require the screen width 7261 to be a multiple of 4. When scaling x11vnc will round the width to the 7262 nearest multiple of 4. To disable this use the ":n4" sub option (like 7263 ":nb" in the previous paragraph; to specify both use a comma: 7264 ":nb,n4", etc.) 7265 7266 If one desires per-client scaling for something like 1:1 from a 7267 workstation and 1:2 from a smaller device (e.g. handheld), currently 7268 the only option is to run two (or more) x11vnc processes with 7269 different scalings listening on separate ports (-rfbport option, etc.) 7270 7271 Update: As of May/2006 x11vnc also supports the UltraVNC server-side 7272 scaling. This is a per-client scaling by factors 1/2, 1/3, ... and so 7273 may be useful for PDA's ("-scale 1/2", etc. will give similar results 7274 except that it applies to all clients.) You may need to supply 7275 "-rfbversion 3.6" for this to be recognized by UltraVNC viewers. 7276 7277 BTW, whenever you run two or more x11vnc's on the same X display and 7278 use the GUI, then to avoid all of the x11vnc's simultaneously 7279 answering the gui you will need to use something like "-connect file1 7280 -gui ..." with different connect files for each x11vnc you want to 7281 control via the gui (or remote-control.) The "-connect file1" usage 7282 gives separate communication channels between a x11vnc process and the 7283 gui process. Otherwise they all share the same X property channels: 7284 VNC_CONNECT and X11VNC_REMOTE. 7285 7286 Update: As of Mar/2005 x11vnc now scales the mouse cursor with the 7287 same scale factor as the screen. If you don't want that, use the 7288 "-scale_cursor frac" option to set the cursor scaling to a different 7289 factor (e.g. use "-scale_cursor 1" to keep the cursor at its natural 7290 unscaled size.) 7291 7292 7293 Q-101: Does x11vnc work with Xinerama? (i.e. multiple monitors joined 7294 together to form one big, single screen.) 7295 7296 Yes, it should generally work because it simply polls the big 7297 effective screen. 7298 7299 If the viewing-end monitor is not as big as the remote Xinerama 7300 display, then the vncviewer scrollbars, etc, will have to be used to 7301 pan across the large area. However one user started two x11vnc's, one 7302 with "-clip 1280x1024+0+0" and the other with "-clip 1280x1024+1280+0" 7303 to split the big screen into two and used two VNC viewers to access 7304 them. 7305 7306 As of Jun/2008: Use "-clip xinerama0" to clip to the first xinerama 7307 sub-screen (if xinerama is active.) xinerama1 for the 2nd sub-screen, 7308 etc. This way you don't need to figure out the WxH+X+Y of the desired 7309 xinerama sub-screen. screens are sorted in increasing distance from 7310 the (0,0) origin (I.e. not the Xserver's order.) 7311 7312 There are a couple potential issues with Xinerama however. If the 7313 screen is not rectangular (e.g. 1280x1024 and 1024x768 monitors joined 7314 together), then there will be "non-existent" areas on the screen. The 7315 X server will return "garbage" image data for these areas and so they 7316 may be distracting to the viewer. The -blackout x11vnc option allows 7317 you to blacken-out rectangles by manually specifying their WxH+X+Y 7318 geometries. If your system has the libXinerama library, the -xinerama 7319 x11vnc option can be used to have it automatically determine the 7320 rectangles to be blackened out. (Note on 8bpp PseudoColor displays the 7321 fill color may not be black.) Update: -xinerama is now on by default. 7322 7323 Some users have reported that the mouse does not behave properly for 7324 their Xinerama display: i.e. the mouse cannot be moved to all regions 7325 of the large display. If this happens try using the -xwarppointer 7326 option. This instructs x11vnc to fake mouse pointer motions using the 7327 XWarpPointer function instead of the XTestFakeMotionEvent XTEST 7328 function. (This may be due to a bug in the X server for XTEST when 7329 Xinerama is enabled.) Update: As of Dec/2006 -xwarppointer will be 7330 applied automatically if Xinerama is detected. To disable use: 7331 -noxwarppointer 7332 7333 7334 Q-102: Can I use x11vnc on a multi-headed display that is not Xinerama 7335 (i.e. separate screens :0.0, :0.1, ... for each monitor)? 7336 7337 You can, but it is a little bit awkward: you must start separate 7338 x11vnc processes for each screen, and on the viewing end start up 7339 separate VNC viewer processes connecting to them. e.g. on the remote 7340 end: 7341 x11vnc -display :0.0 -bg -q -rfbport 5900 7342 x11vnc -display :0.1 -bg -q -rfbport 5901 7343 7344 (this could be automated in the display manager Xsetup for example) 7345 and then on the local machine where you are sitting: 7346 vncviewer somehost:0 & 7347 vncviewer somehost:1 & 7348 7349 Note: if you are running on Solaris 8 or earlier you can easily hit up 7350 against the maximum of 6 shm segments per process (for Xsun in this 7351 case) from running multiple x11vnc processes. You should modify 7352 /etc/system as mentioned in another FAQ to increase the limit. It is 7353 probably also a good idea to run with the -onetile option in this case 7354 (to limit each x11vnc to 3 shm segments), or even -noshm to use no shm 7355 segments. 7356 7357 7358 Q-103: Can x11vnc show only a portion of the display? (E.g. for a 7359 special purpose application or a very large screen.) 7360 7361 As of Mar/2005 x11vnc has the "-clip WxH+X+Y" option to select a 7362 rectangle of width W, height H and offset (X, Y). Thus the VNC screen 7363 will be the clipped sub-region of the display and be only WxH in size. 7364 One user used -clip to split up a large Xinerama screen into two more 7365 managable smaller screens. 7366 7367 This also works to view a sub-region of a single application window if 7368 the -id or -sid options are used. The offset is measured from the 7369 upper left corner of the selected window. 7370 7371 7372 Q-104: Does x11vnc support the XRANDR (X Resize, Rotate and 7373 Reflection) extension? Whenever I rotate or resize the screen x11vnc 7374 just seems to crash. 7375 7376 As of Dec/2004 x11vnc supports XRANDR. You enable it with the -xrandr 7377 option to make x11vnc monitor XRANDR events and also trap X server 7378 errors if the screen change occurred in the middle of an X call like 7379 XGetImage. Once it traps the screen change it will create a new 7380 framebuffer using the new screen. 7381 7382 If the connected vnc viewers support the NewFBSize VNC extension 7383 (Windows TightVNC viewer and RealVNC 4.0 windows and Unix viewers do) 7384 then the viewer will automatically resize. Otherwise, the new 7385 framebuffer is fit as best as possible into the original viewer size 7386 (portions of the screen may be clipped, unused, etc.) For these 7387 viewers you can try the -padgeom option to make the region big enough 7388 to hold all resizes and rotations. We have fixed this problem for the 7389 TightVNC Viewer on Unix: SSVNC 7390 7391 If you specify "-xrandr newfbsize" then vnc viewers that do not 7392 support NewFBSize will be disconnected before the resize. If you 7393 specify "-xrandr exit" then all will be disconnected and x11vnc will 7394 terminate. 7395 7396 7397 Q-105: Independent of any XRANDR, can I have x11vnc rotate and/or 7398 reflect the screen that the VNC viewers see? (e.g. for a handheld 7399 whose screen is rotated 90 degrees.) 7400 7401 As of Jul/2006 there is the -rotate option allow this. E.g's: "-rotate 7402 +90", "-rotate -90", "-rotate x", etc. 7403 7404 7405 Q-106: Why is the view in my VNC viewer completely black? Or why is 7406 everything flashing around randomly? 7407 7408 See the next FAQ for a possible explanation. 7409 7410 7411 Q-107: I use Linux Virtual Terminals (VT's) to implement 'Fast User 7412 Switching' between users' sessions (e.g. Betty is on Ctrl-Alt-F7, 7413 Bobby is on Ctrl-Alt-F8, and Sid is on Ctrl-Alt-F1: they use those 7414 keystrokes to switch between their sessions.) How come the view in a 7415 VNC viewer connecting to x11vnc is either completely black or 7416 otherwise all messed up unless the X session x11vnc is attached to is 7417 in the active VT? 7418 7419 This seems to have to do with how applications (the X server processes 7420 in this case) must "play nicely" if they are not on the active VT 7421 (sometimes called VC for virtual console.) That is, they should not 7422 read from the keyboard or mouse or manage the video display unless 7423 they have the active VT. Given that it appears the XGetImage() call 7424 must ultimately retrieve the framebuffer data from the video hardware 7425 itself, it would make sense x11vnc's polling wouldn't work unless the 7426 X session had active control of the VT. 7427 7428 There does not seem to be an easy way to work around this. Even xwd(1) 7429 doesn't work in this case (try it.) Something would need to be done at 7430 a lower level, say in the XFree86/Xorg X server. Also, using the 7431 Shadow Framebuffer (a copy of the video framebuffer is kept in main 7432 memory) does not appear to fix the problem. 7433 7434 If no one is sitting at the workstation and you just want to remotely 7435 switch the VT over to the one associated with your X session (so 7436 x11vnc can poll it correctly), one can use the chvt(1) command, e.g. 7437 "chvt 7" for VT #7. 7438 7439 7440 Q-108: I am using x11vnc where my local machine has "popup/hidden 7441 taskbars" and the remote display where x11vnc runs also has 7442 "popup/hidden taskbars" and they interfere and fight with each other. 7443 What can I do? 7444 7445 When you move the mouse to the edge of the screen where the popups 7446 happen, the taskbars interfere with each other in strange ways. This 7447 sometimes happens where the local machine is GNOME or Mac OS X and the 7448 remote machine is GNOME. Is there a way to temporarily disable one or 7449 both of these magic desktop taskbars? 7450 7451 One x11vnc user suggests: it should be straightforward to right mouse 7452 click on the task bar panel, and uncheck "enable auto-hide" from the 7453 panel properties dialog box. This will make the panel always visible. 7454 7455 Q-109: Help! x11vnc and my KDE screensaver keep switching each other 7456 on and off every few seconds. 7457 7458 This is a new (Jul/2006) problem seen, say, on the version of KDE that 7459 is shipped with SuSE 10.1. It is not yet clear what is causing this... 7460 If you move the mouse through x11vnc the screensaver shuts off like it 7461 should but then a second or two after you stop moving the mouse the 7462 screensaver snaps back on. 7463 7464 This may be a bug in kdesktop_lock. For now the only workaround is to 7465 disable the screensaver. You can try using another one such as 7466 straight xscreensaver (see the instructions here for how to disable 7467 kdesktop_lock.) If you have more info on this or see it outside of KDE 7468 please let us know. 7469 7470 Update: It appears this is due to kdesktop_lock enabling the screen 7471 saver when the Monitor is in DPMS low-power state (e.g. standby, 7472 suspend, or off.) In Nov/2006 the x11vnc -nodpms option was added as a 7473 workaround. Normally it is a good thing that the monitor powers down 7474 (since x11vnc can still poll the framebuffer in this state), but if 7475 you experience the kdesktop_lock problem you can specify the "-nodpms" 7476 option to keep the Monitor out of low power state while VNC clients 7477 are connected. This is basically the same as typing "xset dpms force 7478 on" periodically. (if you don't want to do these things just disable 7479 the screensaver.) Feel free to file a bug against kdesktop_lock with 7480 KDE. 7481 7482 Q-110: I am running the compiz 3D window manager (or beryl, MythTv, 7483 Google Earth, or some other OpenGL app) and I do not get screen 7484 updates in x11vnc. 7485 7486 This appears to be because the 3D OpenGL/GLX hardware screen updates 7487 do not get reported via the XDAMAGE mechanism. So this is a bug in 7488 compiz/beryl or XDAMAGE/Xorg or the (possibly 3rd party) video card 7489 driver. 7490 7491 As a workaround apply the -noxdamage option. As of Feb/2007 x11vnc 7492 will try to autodetect the problem and disable XDAMAGE if is appears 7493 to be missing a lot of updates. But if you know you are using compiz 7494 you might as well always supply -noxdamage. Thanks to this user who 7495 reported the problem and discovered the workaround. 7496 7497 A developer for MiniMyth reports that the 'alphapulse' tag of the 7498 theme G.A.N.T. can also cause problems, and should be avoided when 7499 using VNC. 7500 7501 Please report a bug or complaint to Beryl/Compiz and/or Xorg about 7502 this: running x11vnc with -noxdamage disables a nice improvement in 7503 responsiveness (especially for typing) and also leads to unnecessary 7504 CPU and memory I/O load due to the extra polling. 7505 7506 Update: as of May/2010 NVIDIA may have fixed this problem in their 7507 proprietary drivers. See the NVIDIA Release Notes. (look for 7508 'x11vnc'.) 7509 7510 Q-111: Can I use x11vnc to view my VMWare session remotely? 7511 7512 Yes, since VMWare usually runs as an X application you can view it via 7513 x11vnc in the normal way. 7514 7515 Note that VMWare has several viewing modes: 7516 * Normal X application window (with window manager frame) 7517 * Quick-Switch mode (with no window manager frame) 7518 * Fullscreen mode 7519 7520 The way VMWare does Fullscreen mode on Linux is to display the Guest 7521 desktop in a separate Virtual Terminal (e.g. VT 8) (see this FAQ on 7522 VT's for background.) Unfortunately, this Fullscreen VT is not an X 7523 server. So x11vnc cannot access it (however, see this discussion of 7524 -rawfb for a possible workaround.) x11vnc works fine with "Normal X 7525 application window" and "Quick-Switch mode" because these use X. 7526 7527 Update: It appears the in VMWare 5.x the Fullscreen mode is X, so 7528 x11vnc access does work. 7529 7530 One user reports he left his machine with VMWare in the Fullscreen 7531 mode, and even though his X session wasn't in the active VT, he could 7532 still connect x11vnc to the X session and pass the keystrokes Ctrl-Alt 7533 (typing "blind") to the VMWare X app. This induced VMWare to switch 7534 out of Fullscreen into Normal X mode and he could continue working in 7535 the Guest desktop remotely. 7536 7537 7538 Aside: Sometimes it is convenient (for performance, etc.) to start 7539 VMWare in its own X session using startx(1). This can be used to have 7540 a minimal window manger (e.g. twm or even no window manager), to 7541 improve response. One can also cut the display depth (e.g. to 16bpp) 7542 in this 2nd X session to improve video performance. This 2nd X session 7543 emulates Fullscreen mode to some degree and can be viewed via x11vnc 7544 as long as the VMWare X session is in the active VT. 7545 7546 Also note that with a little bit of playing with "xwininfo -all 7547 -children" output one can extract the (non-toplevel) window-id of the 7548 of the Guest desktop only when VMWare is running as a normal X 7549 application. Then one can export just the guest desktop (i.e. without 7550 the VMWare menu buttons) by use of the -id windowid option. The 7551 caveats are the X session VMWare is in must be in the active VT and 7552 the window must be fully visible, so this mode is not terribly 7553 convenient, but could be useful in some circumstances (e.g. running 7554 VMWare on a very powerful server machine in a server room that happens 7555 to have a video card, (but need not have a monitor, Keyboard or 7556 mouse).) 7557 7558 7559 7560 [Exporting non-X11 devices via VNC] 7561 7562 Q-112: Can non-X devices (e.g. a raw framebuffer) be viewed (and even 7563 controlled) via VNC with x11vnc? 7564 7565 As of Apr/2005 there is support for this. Two options were added: 7566 "-rawfb string" (to indicate the raw frame buffer device, file, etc. 7567 and its parameters) and "-pipeinput command" (to provide an external 7568 program that will inject or otherwise process mouse and keystroke 7569 input.) Some useful -pipeinput schemes, VID, CONSOLE, and UINPUT, have 7570 since been built into x11vnc for convenience. 7571 7572 This non-X mode for x11vnc is somewhat experimental because it is so 7573 removed in scope from the intended usage of the tool. Incomplete 7574 attempt is made to make all of the other options consistent with non-X 7575 framebuffer polling. So all of the X-related options (e.g. 7576 -add_keysyms, -xkb) are just ignored or may cause an error if used. Be 7577 careful applying such an option via remote control. 7578 7579 The format for the -rawfb string is: 7580 -rawfb <type>:<object>@<W>x<H>x<bpp>[-<BPL>][:<R>/<G>/<B>][+<offset>] 7581 7582 There are also some useful aliases (e.g. "console".) Some examples: 7583 -rawfb shm:210337933@800x600x32:ff/ff00/ff0000 7584 7585 -rawfb map:/dev/fb0@1024x768x16 7586 7587 -rawfb map:/tmp/Xvfb_screen0@640x480x8+3232 7588 7589 -rawfb file:/tmp/my.pnm@250x200x24+37 7590 7591 -rawfb file:/dev/urandom@128x128x8 7592 7593 -rawfb snap:/dev/video0@320x240x24 -24to32 7594 7595 -rawfb console 7596 7597 -rawfb vt2 7598 7599 -rawfb video 7600 7601 -rawfb setup:mycmd.sh 7602 7603 So the type can be "shm" for shared memory objects, and "map" or 7604 "file" for file objects. "map" uses mmap(2) to map the file into 7605 memory and is preferred over "file" (that uses the slower lseek(2) 7606 access method.) Only use file if map isn't working. BTW, "mmap" is an 7607 alias for "map" and if you do not supply a type and the file exists, 7608 map is assumed (see the -help output and below for some exceptions to 7609 this.) The "snap:" setting applies the -snapfb option with "file:" 7610 type reading (this is useful for exporting webcams or TV tuner video; 7611 see the next FAQ for more info.) 7612 7613 Also, if the string is of the form "setup:cmd" then cmd is run and the 7614 first line of its output retrieved and used as the rawfb string. This 7615 allows initializing the device, determining WxHxB, etc. 7616 7617 The object will be the numerical shared memory id for the case of shm. 7618 The idea here is some other program has created this shared memory 7619 segment and periodically updates it with new framebuffer data. x11vnc 7620 polls the area for changes. See shmat(2) and ipcs(8) for more info. 7621 The ipcs command will list current shared memory segments on the 7622 system. Sometimes you can snoop on a program's framebuffer it did not 7623 expect you would be polling! 7624 7625 The object will be the path to the regular or character special file 7626 for the cases of map and file. The idea here is that in the case of a 7627 regular file some other program is writing/updating framebuffer image 7628 data to it. In the case of a character special (e.g. /dev/fb0) it is 7629 the kernel that is "updating" the framebuffer data. 7630 7631 In most cases x11vnc needs to be told the width, height, and number of 7632 bits per pixel (bpp) of the framebuffer. This is the @WxHxB field. For 7633 the case of the Linux framebuffer device, /dev/fb0, the fbset(8) may 7634 be of use (but may not always be accurate for what is currently 7635 viewable.) In general some guessing may be required, especially for 7636 the bpp. Update: in "-rawfb console" mode x11vnc will use the linuxfb 7637 API to try to guess (it is still not always accurate.) Also try 7638 "-rawfb vtN" (on x11vnc 0.9.7 and later) for the N-th Linux text 7639 console (aka virtual terminal.) If the number of Bytes Per Line is not 7640 WxHxB/8 (i.e. the framebuffer lines are padded) you can specify this 7641 information after WxHxB via "-BPL", e.g. @800x600x16-2048 7642 7643 Based on the bpp x11vnc will try to guess the red, green, and blue 7644 masks (these indicate which bits correspond to each color.) It if gets 7645 it wrong you can specify them manually via the optional ":R/G/B" 7646 field. E.g. ":0xff0000/0x00ff00/0x0000ff" (this is the default for 7647 32bpp.) 7648 7649 Finally, the framebuffer may not begin at the beginning of the memory 7650 object, so use the optional "+offset" parameter to indicate where the 7651 framebuffer information starts. So as an example, the Xvfb virtual 7652 framebuffer has options -shmem and -fbdir for exporting its virtual 7653 screen to either shm or a mapped file. The format of these is XWD and 7654 so the initial header should be skipped. BTW, since XWD is not 7655 strictly RGB the view will only be approximate, but usable. Of course 7656 for the case of Xvfb x11vnc can poll it much better via the X API, but 7657 you get the idea. 7658 7659 By default in -rawfb mode x11vnc will actually close any X display it 7660 happened to open. This is basically to shake out bugs (e.g it will 7661 crash rather than mysteriously interacting with the X display.) If you 7662 want x11vnc to keep the X display open while polling the raw 7663 framebuffer prefix a "+" sign at the beginning of the string (e.g. 7664 +file:/dev/urandom@64x64x8) This could be convenient for keeping the 7665 remote control channel active (it uses X properties.) The "-connect 7666 /path/to/file" mechanism could also be used for remote control to 7667 avoid the X property channel. Rare usage, but if you also supply 7668 -noviewonly in this "+" mode then the mouse and keyboard input are 7669 still sent to the X display, presumably for doing something amusing 7670 with /dev/fb... 7671 7672 Interesting Devices:. Here are some aliases for interesting device 7673 files that can be polled via -rawfb: 7674 -rawfb console /dev/fb0 Linux Console 7675 -rawfb vt2 /dev/vcsa2 Linux Console (e.g. virtual ter 7676 minal #2) 7677 -rawfb video /dev/video0 Video4Linux Capture device 7678 -rawfb rand /dev/urandom Random Bytes 7679 -rawfb null /dev/zero Zero Bytes (black screen) 7680 7681 The Linux console, /dev/fb0, etc needs to have its driver enabled in 7682 the kernel. Some of the drivers are video card specific and 7683 accelerated. The console is either the Text consoles (usually 7684 tty1-tty6), or X graphical display (usually starting at tty7.) In 7685 addition to the text console other graphical ones may be viewed and 7686 interacted with as well, e.g. DirectFB or SVGAlib apps, VMWare non-X 7687 fullscreen, or Qt-embedded apps (PDAs/Handhelds.) By default the 7688 pipeinput mechanisms UINPUT and CONSOLE (keystrokes only) are 7689 automatically attempted in this mode under "-rawfb console". 7690 7691 The Video4Linux Capture device, /dev/video0, etc is either a Webcam or 7692 a TV capture device and needs to have its driver enabled in the 7693 kernel. See this FAQ for details. If specified via "-rawfb Video" then 7694 the pipeinput method "VID" is applied (it lets you change video 7695 parameters dynamically via keystrokes.) 7696 7697 The last two, /dev/urandom and /dev/zero are just for fun, but are 7698 also useful in testing. 7699 7700 7701 All of the above -rawfb options are just for viewing the raw 7702 framebuffer (although some of the aliases do imply keystroke and mouse 7703 pipeinput methods.) That may be enough for certain applications of 7704 this feature (e.g. suppose a video camera mapped its framebuffer into 7705 memory and you just wanted to look at it via VNC.) 7706 To handle the pointer and keyboard input from the viewer users the 7707 "-pipeinput cmd" option was added to indicate a helper program to 7708 process the user input. The input is streamed to it and looks 7709 something like this: 7710 Pointer 1 205 257 0 None 7711 Pointer 1 198 253 0 None 7712 Pointer 1 198 253 1 ButtonPress-1 7713 Pointer 1 198 253 0 ButtonRelease-1 7714 Pointer 1 198 252 0 None 7715 Keysym 1 1 119 w KeyPress 7716 Keysym 1 0 119 w KeyRelease 7717 Keysym 1 1 65288 BackSpace KeyPress 7718 Keysym 1 0 65288 BackSpace KeyRelease 7719 Keysym 1 1 112 p KeyPress 7720 Keysym 1 0 112 p KeyRelease 7721 7722 Run "-pipeinput tee:/bin/cat" to get a description of the format. Note 7723 that the -pipeinput option is independent of -rawfb mode and so may 7724 have some other interesting uses. The "tee:" prefix means x11vnc will 7725 both process the user input and pipe it to the command. The default is 7726 to just pipe it to the -pipeinput command. 7727 7728 Note the -pipeinput helper program could actually control the raw 7729 framebuffer. In the libvncserver CVS a simple example program 7730 x11vnc/misc/slide.pl is provided that demonstrates a simple jpeg 7731 "slideshow" application. Also the builtin "-pipeinput VID" mode does 7732 this for webcams and TV capture devices (/dev/video0.) 7733 7734 The -pipeinput program is run with these environment variables set: 7735 X11VNC_PID, X11VNC_PROG, X11VNC_CMDLINE, X11VNC_RAWFB_STR to aid its 7736 knowing what is up. 7737 7738 Another example provided in libvncserver CVS is a script to inject 7739 keystrokes into the Linux console (e.g. the virtual consoles: 7740 /dev/tty1, /dev/tty2, etc) in x11vnc/misc/vcinject.pl. It is based on 7741 the vncterm/LinuxVNC.c program also in the libvncserver CVS. So to 7742 view and interact with VT #2 (assuming it is the active VT) one can 7743 run something like: 7744 x11vnc -rawfb map:/dev/fb0@1024x768x16 -pipeinput './vcinject.pl 2' 7745 7746 This assumes your Linux framebuffer device (/dev/fb0) is properly 7747 configured. See fbset(8) and other documentation. Try 7748 "file:/dev/fb0@WxHxB" as a last resort. Starting with x11vnc 0.8.1, 7749 the above VT injection is built in, as well as WxHxB determination. 7750 Just use something like: 7751 x11vnc -rawfb console 7752 7753 this will try to guess the active virtual console (via /dev/tty0) and 7754 also the /dev/fb0 WxHxB and rgb masks automatically. Use, e.g., 7755 "-rawfb console3" to force the VT number. This input method can be 7756 used generally via "-pipeinput CONSOLE". Also starting with x11vnc 7757 0.8.2 the "-pipeinput UINPUT" mode is tried first (it does both 7758 keyboard and mouse input) and then falls back to CONSOLE mode if it is 7759 not available. Here is the -help output for this mode: 7760 7761 If the rawfb string begins with "console" the framebuffer device 7762 /dev/fb0 is opened (this requires the appropriate kernel modules to 7763 be installed) and so is /dev/tty0. The latter is used to inject 7764 keystrokes (not all are supported, but the basic ones are.) You 7765 will need to be root to inject keystrokes. /dev/tty0 refers to the 7766 active VT, to indicate one explicitly, use "console2", etc. using 7767 the VT number. 7768 7769 If the Linux version seems to be 2.6 or later and the "uinput" 7770 module appears to be present, then the uinput method will be used 7771 instead of /dev/ttyN. uinput allows insertion of BOTH keystrokes 7772 and mouse input and so it preferred when accessing graphical (e.g. 7773 Qt-embedded) linux console apps. See -pipeinput UINPUT below for 7774 more information on this mode (you may want to also use the 7775 -nodragging and -cursor none options.) Use "console0", etc or 7776 -pipeinput CONSOLE to force the /dev/ttyN method. 7777 7778 Note you can change VT remotely using the chvt(1) command. 7779 Sometimes switching out and back corrects the framebuffer state. 7780 7781 To skip input injecting entirely use "consolex". 7782 7783 The string "/dev/fb0" (1, etc) can be used instead of "console". 7784 This can be used to specify a different framebuffer device, e.g. 7785 /dev/fb1. As a shortcut the "/dev/" can be dropped. If the name is 7786 something nonstandard, use "console:/dev/foofb" 7787 7788 If you do not want x11vnc to guess the framebuffer's WxHxB and 7789 masks automatically (sometimes the kernel gives inaccurate 7790 information), specify them with a @WxHxB at the end of the string. 7791 7792 The above is just an example of what can be done. Note that if you 7793 really want to view and interact with the Linux Text console it is 7794 better to use the more accurate and faster LinuxVNC program. The 7795 advantage x11vnc -rawfb might have is that it can allow interaction 7796 with a non-text application, e.g. one based on SVGAlib or Qt-embedded 7797 Also, for example the VMWare Fullscreen mode is actually viewable 7798 under -rawfb and can be interacted with if uinput is enabled. 7799 7800 If the Linux uinput driver is available then full keystroke and mouse 7801 input into the Linux console can be performed. You may be able to 7802 enable uinput via commands like these: 7803 modprobe uinput 7804 mknod /dev/input/uinput c 10 223 7805 7806 The -rawfb and -pipeinput features are intended to help one creatively 7807 "get out of a jam" (say on a legacy or embedded device) where X is 7808 absent or doesn't work properly. Feedback and bug reports are welcome. 7809 For more control and less overhead use libvncserver in your own C 7810 program that passes the framebuffer to libvncserver. 7811 7812 7813 Q-113: Can I export the Linux Console (Virtual Terminals) via VNC 7814 using x11vnc? 7815 7816 Yes, you may need to be root to access the devices that make up the 7817 linux console. 7818 7819 To access the active Linux console via the computer's framebuffer try 7820 something like: 7821 x11vnc -rawfb console 7822 x11vnc -rawfb console2 7823 7824 These will try to access the framebuffer through /dev/fb (or /dev/fb0, 7825 etc.) and if it succeeds it will show any text or graphics that is 7826 currently displayed. Keystrokes will be injected via the device 7827 /dev/tty0 (to force an explicit virtual terminal append a number, e.g. 7828 "console2" to select /dev/tty2.) 7829 7830 If your Linux system does not have a framebuffer device (/dev/fb) you 7831 can get one by adding, e.g., vga=0x31B boot parameter. This enables 7832 the VGA framebuffer device at 1280x1024x24. 0x317 gives 1024x768x16, 7833 etc. You can also enable a Linux framebuffer device by modprobing a 7834 framebuffer driver specific to your video card. 7835 7836 Note that this "-rawfb console" mode shows the contents of the 7837 hardware framebuffer, and so will show whatever is on the screen. It 7838 has no concept of Virtual Terminals WRT what there is to view, it 7839 always shows the active virtual terminal. 7840 7841 Another mode is specific to the Linux text Virtual Terminals, it shows 7842 their text and colors (but no graphics) regardless of whether it is 7843 the active VT or not. It is available on x11vnc 0.9.7 and later. 7844 Enable this mode like this: 7845 x11vnc -rawfb vt 7846 x11vnc -rawfb vt2 7847 7848 The former will select the active one, the latter the 2nd VT. x11vnc 7849 implements this mode by opening the current console text file 7850 "/dev/vcsa2" instead of "/dev/fb". In this way it provides the basic 7851 functionality of the LibVNCServer LinuxVNC program. 7852 7853 The vt mode can be a useful way to try to get a machine's X server 7854 working remotely, e.g. you edit /etc/X11/xorg.conf and then type 7855 startx (or similar, e.g. gdm) in the virtual terminal. A 2nd x11vnc 7856 could be used to see if the X server is now working correctly. 7857 7858 Q-114: Can I export via VNC a Webcam or TV tuner framebuffer using 7859 x11vnc? 7860 7861 Yes, this is possible to some degree with the -rawfb option. There is 7862 no X11 involved: snapshots from the video capture device are used for 7863 the screen image data. See the previous FAQ on -rawfb for background. 7864 For best results, use x11vnc version 0.8.1 or later. 7865 7866 Roughly, one would do something like this: 7867 x11vnc -rawfb snap:/dev/video@320x240x32 7868 7869 This requires that the system allows simple read(2) access to the 7870 video device. This is true for video4Linux on Linux kernel 2.6 and 7871 later (it won't work for 2.4, you'll need a separate program to 7872 snapshot to a file that you point -rawfb to; ask me if it is not clear 7873 what to do.) 7874 7875 The "snap:" enforces -snapfb mode which appears to be necessary. The 7876 read pointer for video capture devices cannot be repositioned (which 7877 would be needed for scanline polling), but you can read a full frame 7878 of data from the device. 7879 7880 On Linux, if the Video4Linux API is present or the v4l-info(1) program 7881 (related to xawtv) exists in in PATH, then x11vnc can be instructed to 7882 try it to determine the -rawfb WxHxB parameters for you automatically. 7883 In this case one would just type: 7884 x11vnc -rawfb video 7885 7886 or "-rawfb video1" for the 2nd video device, etc. 7887 7888 x11vnc has also been extended to use the Video4Linux API over v4l-info 7889 if it is available at build time. This enables setting parameters 7890 (e.g. size and brightness) via x11vnc. See the description below. 7891 Without Video4Linux you will need to initialize the settings of the 7892 video device using something like xawtv or spcaview (and then hope the 7893 settings persist until x11vnc reopens the device.) 7894 7895 Many video4linux drivers tend to set the framebuffer to be 24bpp (as 7896 opposed to 32bpp.) Since this can cause problems with VNC viewers, 7897 etc, the -24to32 option will be automatically imposed when in 24bpp. 7898 7899 Note that by its very nature, video capture involves rapid change in 7900 the framebuffer. This is especially true for cameras where slight 7901 wavering in brightness is always happening. This can lead to much 7902 network bandwidth consumption for the VNC traffic and also local CPU 7903 and I/O resource usage. You may want to experiment with "dialing down" 7904 the framerate via the -wait, -slow_fb, or -defer options. Decreasing 7905 the window size and bpp also helps. 7906 7907 7908 Setting Camera/Tuner parameters via x11vnc: 7909 7910 There is also some support for setting parameters of the capture 7911 device. This is done via "-rawfb video:<settings>". This could be 7912 useful for unattended startup at boottime, etc. Here is the -help 7913 description: 7914 7915 A more sophisticated video device scheme allows initializing the 7916 device's settings using: 7917 7918 -rawfb video:<settings> 7919 7920 The prefix could also be, as above, e.g. "video1:" to specify the 7921 device file. The v4l API must be available for this to work. 7922 Otherwise, you will need to try to initialize the device with an 7923 external program, e.g. xawtv, spcaview, and hope they persist when 7924 x11vnc re-opens the device. 7925 7926 <settings> is a comma separated list of key=value pairs. The 7927 device's brightness, color, contrast, and hue can be set to 7928 percentages, e.g. br=80,co=50,cn=44,hu=60. 7929 7930 The device filename can be set too if needed (if it does not start 7931 with "video"), e.g. fn=/dev/qcam. 7932 7933 The width, height and bpp of the framebuffer can be set via, e.g., 7934 w=160,h=120,bpp=16. 7935 7936 Related to the bpp above, the pixel format can be set via the 7937 fmt=XXX, where XXX can be one of: GREY, HI240, RGB555, RGB565, 7938 RGB24, and RGB32 (with bpp 8, 8, 16, 16, 24, and 32 respectively.) 7939 See http://www.linuxtv.org for more info (V4L api.) 7940 7941 For TV/rf tuner cards one can set the tuning mode via tun=XXX where 7942 XXX can be one of PAL, NTSC, SECAM, or AUTO. 7943 7944 One can switch the input channel by the inp=XXX setting, where XXX 7945 is the name of the input channel (Television, Composite1, S-Video, 7946 etc.) Use the name that is in the information about the device that 7947 is printed at startup. 7948 7949 For input channels with tuners (e.g. Television) one can change 7950 which station is selected by the sta=XXX setting. XXX is the 7951 station number. Currently only the ntsc-cable-us (US cable) 7952 channels are built into x11vnc. See the -freqtab option below to 7953 supply one from xawtv. If XXX is greater than 500, then it is 7954 interpreted as a raw frequency in KHz. 7955 7956 Example: 7957 7958 -rawfb video:br=80,w=320,h=240,fmt=RGB32,tun=NTSC,sta=47 7959 7960 one might need to add inp=Television too for the input channel to 7961 be TV if the card doesn't come up by default in that one. 7962 7963 Note that not all video capture devices will support all of the 7964 above settings. 7965 7966 See the -pipeinput VID option below for a way to control the 7967 settings through the VNC Viewer via keystrokes. 7968 7969 As above, if you specify a "@WxHxB..." after the <settings> string 7970 they are used verbatim: the device is not queried for the current 7971 values. Otherwise the device will be queried. 7972 7973 Also, if you supply the "-pipeinput VID" (or use "-rawfb Video") 7974 option you can control the settings to some degree via keystroke 7975 mappings, e.g. B to increase the brightness or Up arrow to change the 7976 TV station: 7977 7978 For "-pipeinput VID" and you are using the -rawfb for a video 7979 capture device, then an internal list of keyboard mappings is used 7980 to set parameters of the video. The mappings are: 7981 7982 "B" and "b" adjust the brightness up and down. 7983 "H" and "h" adjust the hue. 7984 "C" and "c" adjust the colour. 7985 "N" and "n" adjust the contrast. 7986 "S" and "s" adjust the size of the capture screen. 7987 "I" and "i" cycle through input channels. 7988 Up and Down arrows adjust the station (if a tuner) 7989 F1, F2, ..., F6 will switch the video capture pixel 7990 format to HI240, RGB565, RGB24, RGB32, RGB555, and 7991 GREY respectively. See -rawfb video for details. 7992 7993 See also the -freqtab option to supply your own xawtv channel to 7994 frequency mappings for your country (only ntsc-cable-us is built into 7995 x11vnc.) 7996 7997 7998 Q-115: Can I connect via VNC to a Qt-embedded/Qt-enhanced/Qtopia 7999 application running on my handheld, cell phone, or PC using the Linux 8000 console framebuffer (i.e. not X11)? 8001 8002 Yes, the basic method for this is the -rawfb scheme where the Linux 8003 console framebuffer (usually /dev/fb0) is polled and the uinput driver 8004 is used to inject keystrokes and mouse input. Often you will just have 8005 to type: 8006 x11vnc -rawfb console 8007 8008 (you may need to enable the uinput driver on the system via "modprobe 8009 uinput; mknod /dev/input/uinput c 10 223") If this does not find the 8010 correct frame buffer properties figure them out or guess them and use 8011 something like: 8012 x11vnc -rawfb /dev/fb0@640x480x16 8013 8014 Also, to force usage of the uinput injection method use "-pipeinput 8015 UINPUT". See the -pipeinput description for tunable parameters, etc. 8016 8017 One problem with the x11vnc uinput scheme is that it cannot guess the 8018 mouse motion "acceleration" used by the windowing application (e.g. 8019 QWS or X11.) For X11 and Qt-embedded the acceleration is usually 2 8020 (i.e. a dx of 1 from the mouse yields a 2 pixel displacement of the 8021 mouse cursor.) The default x11vnc uses is 2, since that is often used. 8022 However for one Qt-embedded system we needed to do: 8023 x11vnc -rawfb console -pipeinput UINPUT:accel=4.0 8024 8025 to get reasonable positioning of the mouse. 8026 8027 Even with the correct acceleration setting there is still some drift 8028 (probably because of the mouse threshold where the acceleration kicks 8029 in) and so x11vnc needs to reposition the cursor from 0,0 about 5 8030 times a second. See the -pipeinput UINPUT option for tuning parameters 8031 that can be set (there are some experimental thresh=N tuning 8032 parameters as well) 8033 8034 Currently, one can expect mouse input to be a little flakey. All in 8035 all, the Linux framebuffer input mechanism for Qt-embedded framebuffer 8036 apps is not perfect, but it is usable. 8037 8038 If you need to create a smaller x11vnc binary for a handheld 8039 environment be sure to run strip(1) on it and also consider 8040 configuring with, e.g. "env CPPFLAGS='-DSMALL_FOOTPRINT=1' ./configure 8041 ..." to remove rarely used features and large texts (use 2 or 3 8042 instead of 1 to remove more.) Currently (Jul/2006) this can lower the 8043 size of the x11vnc from 1.1MB to 0.6-0.7MB. 8044 8045 The x11vnc uinput method applies to nearly anything on the Linux 8046 framebuffer console, not just Qt-embedded/Qtopia. DirectFB, SDL using 8047 fbcon driver, SVGAlib applications can also be viewed and interacted 8048 with. Even a Linux X session can be viewed and interacted with without 8049 using X11 (and x11vnc does not have to terminate when the X server 8050 restarts!) The Linux Text consoles (F1-F6) also work. 8051 8052 Note that Qt-embedded supplies its own VNC graphics driver, but it 8053 cannot do both the Linux console framebuffer and VNC at the same time, 8054 which is often what is desired from VNC. 8055 8056 Update: We are finding some setups like Qtopia on the IPAQ do not 8057 allow mouse input via uinput. Please help us debug this problem by 8058 trying x11vnc on your device and letting us know what does and does 8059 not work. See the next FAQ for a possible workaround for touchscreens. 8060 8061 8062 Q-116: How do I inject touch screen input into an 8063 Qt-embedded/Qt-enhanced/Qtopia cell phone such as openmoko/qtmoko Neo 8064 Freerunner? 8065 8066 The qtmoko project does not use X11 for the graphical display. 8067 Unfortunately the Linux uinput method described in the previous FAQ 8068 does not work because Qt is using TSLIB (touch screen library) to 8069 process the input and it only reads from one device (often 8070 /dev/input/event1) and not from the new UINPUT device that x11vnc 8071 creates (under -pipeinput UINPUT) 8072 8073 So something else needs to be done. It was discovered that by simply 8074 writing the touchscreen events directly to /dev/input/event1 then 8075 input can be injected into the system. There is no x11vnc builtin mode 8076 for this yet (until we understand it better), but there is a working 8077 script provided in x11vnc/misc/qt_tslib_inject.pl. So one could use it 8078 this way for example: 8079 x11vnc ... -rawfb console -pipeinput path/to/qt_tslib_inject.pl -env INJECT_O 8080 PTIONS=clickonly,cal=/etc/pointercal 8081 8082 Read the script for how to enable other options and what the above 8083 options mean (e.g. /etc/pointercal contains TSLIB's calibration 8084 parameters and are necessary to achieve accurate pointing.) 8085 8086 The x11vnc/misc/qt_tslib_inject.pl script can potentially be modified 8087 to handle other devices where the uinput method fails. It could also 8088 be modified to create 'hot keys', etc. 8089 8090 Please let us know how things go if you try this out; there is much to 8091 learn about synthetic input injection in handhelds and cell phones. As 8092 we learn more we can develop a builtin x11vnc mode for this sort of 8093 injection. 8094 8095 Update Dec/2010: There is experimental built-in UINPUT support in the 8096 x11vnc development tarball for qtmoko with touchpad managed by tslib. 8097 See -pipeinput UINPUT for more info. Here is an example: 8098 x11vnc -rawfb console -pipeinput UINPUT:touch,tslib_cal=/etc/pointercal,dire 8099 ct_abs=/dev/input/event1,nouinput,dragskip=3 8100 8101 8102 Q-117: Now that non-X11 devices can be exported via VNC using x11vnc, 8103 can I build it with no dependencies on X11 header files and libraries? 8104 8105 Yes, as of Jul/2006 x11vnc enables building for -rawfb only support. 8106 Just do something like when building: 8107 ./configure --without-x (plus any other flags) 8108 make 8109 8110 You can then test via "ldd x11vnc" that the binary does not depend on 8111 libX11.so, etc. See the previous FAQ's for non-X11 framebuffer usage. 8112 If you use this for an interesting non-X11 application please let us 8113 know what you did. 8114 8115 8116 Q-118: How do I cross compile x11vnc for a different architecture than 8117 my Linux i386 or amd64 PC? 8118 8119 You will need a cross-compiling toolchain. Perhaps your distro 8120 provides these or you can find a HOWTO for your distro. We found a 8121 nice one at qtmoko.org for building armel binaries on Debian Linux 8122 i386 machines. It includes most of the libraries that x11vnc needs. We 8123 use that example here. 8124 8125 We ran this script to set PATH, configure, and build: 8126 #!/bin/sh 8127 8128 # toolchain from: qtmoko-debian-toolchain-armv4t-eabi.tar.gz 8129 8130 export PATH=/opt/toolchains/arm920t-eabi/bin:$PATH 8131 8132 env CC=arm-linux-gcc ./configure --host=arm-linux --without-avahi 8133 8134 make 8135 8136 arm-linux-strip ./x11vnc/x11vnc 8137 ls -l ./x11vnc/x11vnc 8138 8139 Note we had to include --without-avahi due to lack of 8140 libavahi-client.so.3 supplied by the toolchain we used. One would need 8141 to add it if it was desired on the target machine. We also stripped 8142 the binary to make it smaller. 8143 8144 For an embedded system one may also want to add --without-x if the 8145 embedded system does not use X11 and the -rawfb mechanism must be 8146 used. 8147 8148 8149 Q-119: Does x11vnc support Mac OS X Aqua/Quartz displays natively 8150 (i.e. no X11 involved)? 8151 8152 Yes, since Nov/2006 in the development tree (x11vnc-0.8.4 tarball) 8153 there is support for native Mac OS X Aqua/Quartz displays using the 8154 -rawfb mechanism described above. The mouse and keyboard input is 8155 achieved via Mac OS X API's. 8156 8157 So you can use x11vnc as an alternative to OSXvnc (aka Vine Server), 8158 or Apple Remote Desktop (ARD). Perhaps there is some x11vnc feature 8159 you'd like to use on Mac OS X, etc. For a number of activities (e.g. 8160 window drags) it seems to be faster than OSXvnc. 8161 8162 Notes: 8163 8164 X11: x11vnc will also work (as it has for years) with a X11 server 8165 (XDarwin) running on Mac OS X (people often install this software to 8166 display remote X11 apps on their Mac OS X system, or use some old 8167 favorites locally such as xterm.) However in this case x11vnc will 8168 only work reasonably in single window -id windowid mode (and the 8169 window may need to have mouse focus.) 8170 8171 If you do not have the DISPLAY env. variable set, x11vnc will assume 8172 native Aqua/Quartz on Mac OS X, however if DISPLAY is set it will 8173 assume an X11 connection. Use "-rawfb console" to force the native 8174 display (or unset DISPLAY.) 8175 8176 Update: Leopard sets DISPLAY by default in all sessions. Since it 8177 starts with the string "/tmp/" x11vnc will use that to know if it 8178 should ignore it. Use "-display :0.0" to force it. 8179 8180 Building: If you don't have the X11 build and runtime packages 8181 installed you will need to build it like this: 8182 (cd to the e.g. x11vnc-0.9, source directory) 8183 ./configure --without-x 8184 make 8185 8186 Win2VNC/x2vnc: One handy use is to use the -nofb mode to redirect 8187 mouse and keyboard input to a nearby Mac (i.e. one to the side of your 8188 desk) via x2vnc or Win2VNC. See this FAQ for more info. 8189 8190 Options: Here are the Mac OS X specific x11vnc options: 8191 -macnodim For the native Mac OS X server, disable dimming. 8192 -macnosleep For the native Mac OS X server, disable display sleep 8193 . 8194 -macnosaver For the native Mac OS X server, disable screensaver. 8195 -macnowait For the native Mac OS X server, do not wait for the 8196 user to switch back to his display. 8197 -macwheel n For the native Mac OS X server, set the mouse wheel 8198 speed to n (default 5.) 8199 -macnoswap For the native Mac OS X server, do not swap mouse 8200 buttons 2 and 3. 8201 -macnoresize For the native Mac OS X server, do not resize or rese 8202 t 8203 the framebuffer even if it is detected that the scree 8204 n 8205 resolution or depth has changed. 8206 -maciconanim n For the native Mac OS X server, set n to the number 8207 of milliseconds that the window iconify/deiconify 8208 animation takes. In -ncache mode this value will be 8209 used to skip the animation if possible. (default 400) 8210 -macmenu For the native Mac OS X server, in -ncache client-sid 8211 e 8212 caching mode, try to cache pull down menus (not perfe 8213 ct 8214 because they have animated fades, etc.) 8215 8216 PasteBoard/Clipboard: There is a bug that the Clipboard (called 8217 PasteBoard on Mac it appears) exchange will not take place unless 8218 x11vnc was started from inside the Aqua display (e.g. started inside a 8219 Terminal app window.) Otherwise it cannot connect to the PasteBoard 8220 server. So Clipboard exchange won't work for our standard "ssh in" 8221 startup scheme. 8222 8223 Hopefully this deficiency can be removed, but until then for Clipboard 8224 exchange to work you will need to start x11vnc inside the desktop 8225 session (i.e. either start it running before you leave, or start up a 8226 2nd x11vnc inside from a 1st one started outside, or use the apple 8227 script below) 8228 8229 Here also is a osascript trick that seems to work (it opens the 8230 Terminal app and instructs it to start x11vnc): 8231 8232 #!/bin/sh 8233 # 8234 # start_x11vnc: start x11vnc in a Terminal window 8235 # (this will allow Clipboard/Pasteboard exchange to work) 8236 8237 tmp=/tmp/start_x11vnc.$$ 8238 8239 cat > $tmp <<END 8240 8241 tell application "Terminal" 8242 activate 8243 do script with command "$HOME/x11vnc -rfbauth .vnc/passwd -ssl SAVE" 8244 end tell 8245 8246 END 8247 8248 osascript $tmp 8249 rm -f $tmp 8250 8251 where you should customize the x11vnc command line to your needs and 8252 the full path to the binary. Save it in a file e.g. "start_x11vnc" and 8253 then after you SSH in just type "./start_x11vnc" (or have ssh run the 8254 command for you.) Then once you are connected via VNC, iconify the 8255 Terminal windows (you can't delete them since that will kill x11vnc.) 8256 8257 Update Aug/2010: A user reports the following useful information: 8258 This is not a problem on Mac OS X 10.6.x (Snow Leopard) when connecting 8259 via ssh to start x11vnc. And, on Mac OS X 10.5.x (Leopard), the problem 8260 can be permanently eliminated by doing this: 8261 8262 8263 sudo /usr/libexec/PlistBuddy -c 'delete :LimitLoadToSessionType' \ 8264 -c 'add :LimitLoadToSessionType string Background' \ 8265 /System/Library/LaunchAgents/com.apple.pboard.plist 8266 # ignore any 'Delete: Entry, ":LimitLoadToSessionType", Does Not Exist' message 8267 8268 and then restarting (yes, you must restart not just log off). But 8269 ONLY do that for Mac OS X 10.5.x and NOT for 10.6.x (which doesn't 8270 need it anyway). 8271 8272 We recently got access to a MacOSX 10.6.4 (Snow Leopard) macbook and 8273 have confirmed that the above is correct. 8274 8275 8276 Q-120: Can x11vnc be used as a VNC reflector/repeater to improve 8277 performance for the case of a large number of simultaneous VNC viewers 8278 (e.g. classroom broadcasting or a large demo)? 8279 8280 Yes, as of Feb/2007 there is the "-reflect host:N" option to connect 8281 to the VNC server "host:N" (either another x11vnc or any other VNC 8282 server) and re-export it. VNC viewers then connect to the x11vnc(s) 8283 running -reflect. 8284 8285 The -reflect option is the same as: "-rawfb vnc:host:N". See the 8286 -rawfb description under "VNC HOST" for more details. 8287 8288 You can replace "host:N" with "listen" or "listen:port" for reverse 8289 connections. 8290 8291 One can set up a number of such reflectors/repeaters to spread the 8292 resource usage around, e.g.: 8293 C -------<-------| 8294 C -------<-------| 8295 C -------<-------|---- R -----| 8296 C -------<-------| | 8297 C -------<-------| | 8298 | 8299 C -------<-------| | 8300 C -------<-------| | 8301 C -------<-------|---- R -----| 8302 C -------<-------| | 8303 C -------<-------| | 8304 |====== S 8305 C -------<-------| | 8306 C -------<-------| | 8307 C -------<-------|---- R -----| 8308 C -------<-------| | 8309 C -------<-------| | 8310 | 8311 C -------<-------| | 8312 C -------<-------| | 8313 C -------<-------|---- R -----| 8314 C -------<-------| 8315 C -------<-------| 8316 8317 Where "S" is the original VNC Server, "C" denote VNC viewer clients, 8318 and "R" denotes an x11vnc running -reflect to "S". 8319 8320 Ideally, a client "C" will be fairly close network-wise to its "R". It 8321 is fine to run the "R" on the same machine as one of its "C's". A nice 8322 setup for a large, (e.g. 64-128) viewer classroom broadcast case would 8323 be to run R's on areas isolated by network switches, e.g. one R per 8324 switch. 8325 8326 In an extreme case (e.g. 1000 viewers) one might actually need a 2nd 8327 layer of R's in the tree. If you try something like that let us know! 8328 8329 There are many resource savings in doing something like the above. The 8330 first obvious one is network bandwidth savings. Another is less CPU 8331 load on "S" since it handles many fewer simultaneous connections. 8332 Also, if there are a few clients C on very slow links, their presence 8333 does not slow down every other client, just the clients on their "R". 8334 One way a slow client affects things is if there are some large 8335 framebuffer writes (e.g. jpeg image region) then the repeater may 8336 block waiting for that large write to finish before going onto the 8337 next client (however, if the write is small enough, the kernel will 8338 buffer it and the server can go on to service the next client.) 8339 8340 The x11vnc -reflect implementation uses the libvncclient library in 8341 the LibVNCServer project to handle the connection to "S". It is not 8342 currently very efficient since it simply does its normal framebuffer 8343 polling scheme on the libvncclient framebuffer (which it then 8344 re-exports via VNC to its clients C.) However, CopyRect and 8345 CursorShape encodings are preserved in the reflection and that helps. 8346 Dragging windows with the mouse can be a problem (especially if S is 8347 not doing wireframing somehow, consider -nodragging if the problem is 8348 severe) For a really fast reflector/repeater it would have to be 8349 implemented from scratch with performance in mind. See these other 8350 projects: 8351 http://sourceforge.net/projects/vnc-reflector/, 8352 http://www.tightvnc.com/projector/ (closed source?), 8353 8354 8355 Automation via Reverse Connections: Instead of having the R's 8356 connect directly to S and then the C's connect directly to the R they 8357 should use, some convenience can be achieved by using reverse 8358 connections (the x11vnc ""-connect host1,host2,..." option.) Suppose 8359 all the clients "C" are started up in Listen mode: 8360 client1> vncviewer -listen 8361 client2> vncviewer -listen 8362 client3> vncviewer -listen 8363 ... 8364 client64> vncviewer -listen 8365 8366 (e.g. client1> is the cmdline prompt on machine client1 ... etc) and 8367 all the repeaters R are started like this: 8368 repeater1> x11vnc -reflect listen -connect client1,client2,...client8 8369 repeater2> x11vnc -reflect listen -connect client9,client10,...client16 8370 ... 8371 repeater8> x11vnc -reflect listen -connect client57,client58,...client64 8372 8373 and finally the main server is started to kick the whole thing into 8374 motion: 8375 vncserver> x11vnc -display :0 -connect repeater1,repeater2,...repeater8 8376 8377 (or instruct a non-x11vnc VNC server to reverse connect to the 8378 repeaters.) For a classroom broadcasting setup one might have the 8379 first two sets of commands start automatically at bootup or when 8380 someone logs in, and then start everything up with the S server. One 8381 may even be able to script the forward connection bootstrap case, let 8382 us know what you did. A really nice thing would be some sort of 8383 auto-discovery of your repeater, etc... 8384 8385 Q-121: Can x11vnc be used during a Linux, Solaris, etc. system 8386 Installation so the Installation can be done remotely? 8387 8388 This can be done, but it doesn't always work because it depends on how 8389 the OS does its install. We have to "sneak in" somehow. Note that some 8390 OS's have a remote install (ssh etc.) built in and so you might want 8391 to use that instead. 8392 8393 Usually the OS install will have to be a network-install in order to 8394 have networking up during the install. Otherwise, you may have a 8395 (slim) chance to configure the networking manually (ifconfig(8) and 8396 route(8).) 8397 8398 To avoid library dependencies problems in the typical minimal (e.g. 8399 busybox) installation OS it is a good idea to build a statically 8400 linked x11vnc binary. A way that often works is to do a normal build 8401 and then paste the final x11vnc link line into a shell script. Then 8402 change the "gcc" to "gcc -static" and run the shell script. You may 8403 need to disable features (e.g. "--without-xfixes") if there is not a 8404 static library for the feature available. You may also need to add 8405 extra link options (e.g. "-lXrender") to complete library dependencies 8406 manually. 8407 8408 Let's call the binary x11vnc.static. Place it on a webserver 8409 somewhere. It may be possible to retrieve it via scp(1) too. 8410 8411 During the install you need to get a shell to retreive x11vnc.static 8412 and run it. 8413 8414 If the Solaris install is an older X-based one, there will be a menu 8415 for you to get a terminal window. From that window you might be able 8416 to retrieve x11vnc.static via wget, scp, or ftp. Remember to do "chmod 8417 755 ./x11vnc.static" and then find the -auth file as in this FAQ. 8418 8419 If it is a Linux install that uses an X server (e.g. SuSE and probably 8420 Fedora), then you can often get a shell by pressing Ctrl-Alt-F2 or 8421 similar. Then get the x11vnc binary via something like this: 8422 cd /tmp 8423 wget http://192.168.0.22/x11vnc.static 8424 chmod 755 ./x11vnc.static 8425 8426 Find the name of the auth file as in this FAQ. (maybe run "ps wwaux | 8427 grep auth".) Then run it like this: 8428 ./x11vnc.static -forever -nopw -display :0 -auth /tmp/wherever/the/authfile 8429 8430 then press Alt-F7 to go back to the X install. You should now be able 8431 to connect via a vnc viewer and continue the install. Watch out for 8432 the display being :1, etc. 8433 8434 If there is a firewall blocking incoming connections during the 8435 install, use the "-connect hostname" option option for a reverse 8436 connection to the hostname running the VNC viewer in listen mode. 8437 8438 Debian based installs are either console-text or console-framebuffer 8439 based. These are install (or expert) and installgui (or expertgui) 8440 boot lines, respectively. For the console-text based installs you 8441 probably need to add a boot cmd line option like vga=0x314 (which is 8442 800x600x16) to get the console-text to use the linux framebuffer 8443 device properly. 8444 8445 For a Debian console-text based install after the network is 8446 configured press Ctrl-Alt-F2 to get a shell. Retrieve the binary via 8447 wget as above and chmod 755 it. Then run it something like this: 8448 sleep 10; ./x11vnc.static -forever -nopw -rawfb console 8449 8450 then before the sleep is over press Alt-F1 to get back to the install 8451 virtual console. You should be able to connect via a VNC viewer and 8452 continue with the install. 8453 8454 For a recent (2009) Debian install we booted with "expert vga=0x301" 8455 and "expert vga=0x311" to get console text based installs at 640x480x8 8456 and 640x480x16, respectively (replace "expert" with "install" if you 8457 like.) Otherwise it was giving a 16 color 640x480x4 (4 bit per pixel) 8458 display which x11vnc could not handle. 8459 8460 For Debian console-framebuffer GUI based installs (installgui or 8461 expertgui) we have not be able to enter keystrokes or mouse motions. 8462 This may be resolved if the install had the Linux kernel module 8463 uinput, but it doesn't; one can wget uinput.ko and then run insmod on 8464 it, but the module must match the installation kernel. So, failing 8465 that, you can only do the GUI view-only, which can be handy to watch a 8466 long network install from your desk instead of in front of the machine 8467 being installed. For these, after the network is configured press 8468 Ctrl-Alt-F2 to get a shell. Retrieve the binary via wget as above and 8469 chmod 755 it. Then run it something like this: 8470 sleep 10; ./x11vnc.static -forever -nopw -rawfb console 8471 8472 then before the sleep is over press Alt-F5 to get back to the GUI 8473 install console. You should be able to connect via a VNC viewer and 8474 watch the install. 8475 [Misc: Clipboard, File Transfer/Sharing, Printing, Sound, Beeps, 8476 Thanks, etc.] 8477 8478 Q-122: Does the Clipboard/Selection get transferred between the 8479 vncviewer and the X display? 8480 8481 As of Jan/2004 x11vnc supports the "CutText" part of the RFB (aka VNC) 8482 protocol. When text is selected/copied in the X session that x11vnc is 8483 polling it will be sent to connected VNC viewers. And when CutText is 8484 received from a VNC viewer then x11vnc will set the X11 selections 8485 PRIMARY, CLIPBOARD, and CUTBUFFER0 to it. x11vnc is able to hold the 8486 PRIMARY and CLIPBOARD selections (Xvnc does not seem to do this.) 8487 8488 The X11 selections can be confusing, especially to those coming from 8489 Windows or MacOSX where there is just a single 'Clipboard'. The X11 8490 CLIPBOARD selection is a lot like that of Windows and MacOSX, e.g. 8491 highlighted text is sent to the clipboard when the user activates 8492 "Edit -> Copy" or presses "Control+C" (and pasting it via "Edit -> 8493 Paste" or "Control+V".) The X11 PRIMARY selection has been described 8494 as 'for power users' or 'an Easter Egg'. As soon as text is 8495 highlighted it is set to the PRIMARY selection and so it is 8496 immediately ready for pasting, usually via the Middle Mouse Button or 8497 "Shift+Insert". See this jwz link for more information. 8498 8499 x11vnc's default behavior is to watch both CLIPBOARD and PRIMARY and 8500 whenever one of them changes, it sends the new text to connected 8501 viewers. Note that since the RFB protocol only has a single "CutText" 8502 then both selections are "merged" to some degree (and this can lead to 8503 confusing results.) One user was confused why x11vnc was "forgetting" 8504 his CLIPBOARD selection and the reason was he also changed PRIMARY 8505 some time after he copied text to the clipboard. Usually an app will 8506 set PRIMARY as soon as any text is highlighted so it easy to see how 8507 CLIPBOARD was forgotten. Use the -noprimary described below as a 8508 workaround. Similarly, by default when x11vnc receives CutText it sets 8509 both CLIPBOARD and PRIMARY to it (this is probably less confusing, but 8510 could possibly lead to some failure modes as well.) 8511 8512 You may not like these defaults. Here are ways to change the behavior: 8513 * If you don't want the Clipboard/Selection exchanged at all use the 8514 -nosel option. 8515 * If you want changes in PRIMARY to be ignored use the -noprimary 8516 option. 8517 * If you want changes in CLIPBOARD to be ignored use the 8518 -noclipboard option. 8519 * If you don't want x11vnc to set PRIMARY to the "CutText" received 8520 from viewers use the -nosetprimary option. 8521 * If you don't want x11vnc to set CLIPBOARD to the "CutText" 8522 received from viewers use the -nosetclipboard option. 8523 8524 You can also fine-tune it a bit with the -seldir dir option and also 8525 -input. 8526 8527 You may need to watch out for desktop utilities such as KDE's 8528 "Klipper" that do odd things with the selection, clipboard, and 8529 cutbuffers. 8530 8531 8532 Q-123: Can I use x11vnc to record a Shock Wave Flash (or other format) 8533 video of my desktop, e.g. to record a tutorial or demo? 8534 8535 Yes, it is possible with a number of tools that record VNC and 8536 transform it to swf format or others. One such popular tool is 8537 pyvnc2swf. There are a number of tutorials (broken link?) on how to do 8538 this. Another option is to use the vnc2mpg that comes in the 8539 LibVNCServer package. 8540 An important thing to remember when doing this is that tuning 8541 parameters should be applied to x11vnc to speed up its polling for 8542 this sort of application, e.g. "-wait 10 -defer 10". 8543 8544 Q-124: Can I transfer files back and forth with x11vnc? 8545 8546 As of Oct/2005 and May/2006 x11vnc enables, respectively, the TightVNC 8547 and UltraVNC file transfer implementations that were added to 8548 libvncserver. This currently works with TightVNC and UltraVNC viewers 8549 (and Windows viewers only support filetransfer it appears... but they 8550 do work to some degree under Wine on Linux.) 8551 8552 The SSVNC Unix VNC viewer supports UltraVNC file transfer by use of a 8553 Java helper program. 8554 8555 TightVNC file transfer is off by default, if you want to enable it use 8556 the -tightfilexfer option. 8557 8558 UltraVNC file transfer is off by default, to enable it use something 8559 like "-rfbversion 3.6 -permitfiletransfer" 8560 options (UltraVNC incorrectly uses the RFB protocol version to 8561 determine if its features are available, so x11vnc has to pretend to 8562 be version 3.6.) As of Sep/2006 "-ultrafilexfer" is an alias for these 8563 two options. Note that running as RFB version 3.6 may confuse other 8564 VNC Viewers. 8565 8566 Sadly you cannot do both -tightfilexfer and -ultrafilexfer at the same 8567 time because the latter requires setting the version to 3.6 and 8568 tightvnc will not do filetransfer when it sees that version number. 8569 8570 Also, because of the way the LibVNCServer TightVNC file transfer is 8571 implemented, you cannot do Tightvnc file transfer in -unixpw mode. 8572 However, UltraVNC file transfer does work in -unixpw (but if a client 8573 tries it do a filetransfer during the login process it will be 8574 disconnected.) 8575 8576 IMPORTANT: please understand if -ultrafilexfer or -tightfilexfer is 8577 specified and you run x11vnc as root for, say, inetd or display 8578 manager (gdm, kdm, ...) access and you do not have it switch users via 8579 the -users option, then VNC Viewers that connect are able to do 8580 filetransfer reads and writes as *root*. 8581 8582 The UltraVNC and TightVNC settings can be toggled on and off inside 8583 the gui or by -R remote control. However for TightVNC the changed 8584 setting only applies for NEW clients, current clients retain their 8585 TightVNC file transfer ability. For UltraVNC it works better, however 8586 if an UltraVNC client has initiated a file transfer dialog it will 8587 remain in effect until the dialog is closed. If you want to switch 8588 between UltraVNC and TightVNC file transfer in the gui or by remote 8589 control you will probably be foiled by the "-rfbversion 3.6" issue. 8590 8591 8592 Q-125: Which UltraVNC extensions are supported? 8593 8594 Some of them are supported. To get UltraVNC Viewers to attempt to use 8595 these extensions you will need to supply this option to x11vnc: 8596 -rfbversion 3.6 8597 8598 Or use -ultrafilexfer which is an alias for the above option and 8599 "-permitfiletransfer". UltraVNC evidently treats any other RFB version 8600 number as non-UltraVNC. 8601 8602 Here are a list of the UltraVNC extensions supported by x11vnc: 8603 * ServerInput: "Toggle Remote Input and Remote Blank Monitor" 8604 * FileTransfer: "Open File Transfer..." 8605 * SingleWindow: "Select Single Window..." 8606 * TextChat: "Open Chat..." 8607 * 1/n Server Scaling 8608 8609 The SSVNC Unix VNC viewer supports these UltraVNC extensions. 8610 8611 To disable SingleWindow and ServerInput use -noultraext (the others 8612 are managed by LibVNCServer.) See this option too: -noserverdpms. 8613 8614 Also, the UltraVNC repeater proxy is supported for use with reverse 8615 connections: "-connect repeater://host:port+ID:NNNN". Use it for both 8616 plaintext and SSL connections. This mode can send any string before 8617 switching to the VNC protocol, and so could be used with other 8618 proxy/gateway tools. Also, a perl repeater implemention is here: 8619 ultravnc_repeater.pl 8620 8621 8622 Q-126: Can x11vnc emulate UltraVNC's Single Click helpdesk mode for 8623 Unix? I.e. something very simple for a naive user to initiate a 8624 reverse vnc connection from their Unix desktop to a helpdesk 8625 operator's VNC Viewer. 8626 8627 Yes, UltraVNC's Single Click (SC) mode can be emulated fairly well on 8628 Unix. 8629 8630 We use the term "helpdesk" below, but it could be any sort of remote 8631 assistance you want to set up, e.g. something for Unix-using friends 8632 or family to use. This includes Mac OS X. 8633 8634 Assume you create a helpdesk directory "hd" on your website: 8635 http://www.mysite.com/hd (any website that you can upload files to 8636 should work, although remember the user will be running the programs 8637 you place there.) 8638 8639 In that "hd" subdirectory copy an x11vnc binary to be run on the Unix 8640 user's machine (e.g. Linux, etc) and also create a file named "vnc" 8641 containing the following: 8642 #!/bin/sh 8643 8644 webhost="http://www.mysite.com/hd" # Your helpdesk dir URL. 8645 8646 vnchost="ip.someplace.net" # Your host running 'vncviewer -listen' 8647 # It could also be your IP number. If it is 8648 # a router/firewall, you will need to 8649 # configure it to redirect port 5500 to you 8650 r 8651 # workstation running 'vncviewer -listen' 8652 8653 dir=/tmp/vnc_helpdesk.$$ # Make a temporary working dir. 8654 mkdir $dir || exit 1 8655 cd $dir || exit 1 8656 8657 trap "cd /tmp; rm -rf $dir" 0 2 15 # Cleans up on exit. 8658 8659 wget $webhost/x11vnc # Fetch x11vnc binary. If multi- 8660 chmod 755 ./x11vnc # platform, use $webhost/`uname`/x11vnc 8661 # or similar. 8662 8663 ./x11vnc -connect_or_exit $vnchost -rfbport 0 -nopw 8664 8665 with the hostnames / IP addresses customized to your case. 8666 8667 On the helpdesk VNC viewer machine (ip.someplace.net in this example) 8668 you have the helpdesk operator running VNC viewer in listen mode: 8669 vncviewer -listen 8670 8671 or if on Windows, etc. somehow have the VNC viewer be in "listen" 8672 mode. 8673 8674 Then, when the naive user needs assistance you instruct him to open up 8675 a terminal window on his Unix desktop and paste the following into the 8676 shell: 8677 wget -qO - http://www.mysite.com/hd/vnc | sh - 8678 8679 and then press Enter. You could have this instruction on a web page or 8680 in an email you send him, etc. This requires that the wget is 8681 installed on the user's Unix machine (he might only have curl or lynx, 8682 see below for more info.) 8683 8684 8685 So I guess this is about 3-4 clicks (start a terminal and paste) and 8686 pressing "Enter" instead of "single click"... 8687 8688 See this page for some variations on this method, e.g. how to add a 8689 password, SSL Certificates, etc. 8690 8691 8692 If you don't have a website (there are many free ones) or don't want 8693 to use one you will have to email him all of the ingredients (x11vnc 8694 binary and a launcher script) and tell him how to run it. This could 8695 be easy or challenging depending on the skill of the naive unix 8696 user... 8697 8698 A bit of obscurity security could be put in with a -passwd, -rfbauth 8699 options, etc. (note that x11vnc will require a password even for 8700 reverse connections.) More info here. 8701 8702 8703 Firewalls: If the helpdesk (you) with the vncviewer is behind a 8704 NAT/Firewall/Router the router will have to be configured to redirect 8705 a port (i.e. 5500 or maybe different one if you like) to the vncviewer 8706 machine. If the vncviewer machine also has its own host-level 8707 firewall, you will have to open up the port there as well. 8708 8709 NAT-2-NAT: There is currently no way to go "NAT-2-NAT", i.e. both User 8710 and Helpdesk workstations behind NAT'ing Firewall/Routers without 8711 configuring a router to do a port redirection (i.e. on your side, the 8712 HelpDesk.) To avoid modifying either firewall/router, one would need 8713 some public (IP address reachable on the internet) redirection/proxy 8714 service. Perhaps such a thing exists. http://sc.uvnc.com provides this 8715 service for their UltraVNC Single Click users. 8716 8717 Update: It may be possible to do "NAT-2-NAT" with a UDP tunnel such as 8718 http://samy.pl/pwnat/. All that is required is that both NAT firewalls 8719 allow in UDP packets from an IP address to which a UDP packet has 8720 recently been sent to. If you try it out let us know how it went. 8721 8722 8723 Very Naive Users: 8724 8725 If it is beyond the user how to open a terminal window and paste in a 8726 command (you have my condolences...) you would have to somehow setup 8727 his Web browser to download the "vnc" file (or a script containing the 8728 above wget line) and prompt the user if he wants to run it. This may 8729 be tricky to set up (which is probably a good thing to not have the 8730 web browser readily run arbitrary programs downloaded from the 8731 internet...) 8732 8733 One command-line free way, tested with KDE, is to name the file vnc.sh 8734 and then instruct the user to right-click on the link and do "Save 8735 Link As" to his Desktop. It will appear as an icon, probably one that 8736 looks like a terminal or a command line prompt. He next should 8737 right-click on the icon and select "Properties" and go to the 8738 "Permissions" tab. Then in that dialog select the checkbox "Is 8739 executable". He should then be able to click on the icon to launch it. 8740 Another option is to right-click on the icon and select "Open With -> 8741 Other ..." and for the name of the application type in "/bin/sh". 8742 Unfortunately in both cases the command output is lost and so errors 8743 cannot be debugged as easily. A similar thing appears to work in GNOME 8744 if under "Properties -> Permissions" they click on "Execute" checkbox 8745 for "Owner". Then when they click on the icon, they will get a dialog 8746 where they can select "Run in Terminal". In general for such cases, if 8747 it is feasible, it might be easier to ssh to his machine and set 8748 things up yourself... 8749 8750 8751 SSL Encrypted Helpdesk Connections: 8752 8753 As of Apr/2007 x11vnc supports reverse connections in SSL and so we 8754 can do this. On the Helpdesk side (Viewer) you will need STUNNEL or 8755 better use the Enhanced TightVNC Viewer (SSVNC) package we provide 8756 that automates all of the SSL for you. 8757 8758 To do this create a file named "vncs" in the website "hd" directory 8759 containing the following: 8760 #!/bin/sh 8761 8762 webhost="http://www.mysite.com/hd" # Your helpdesk dir URL. 8763 8764 vnchost="ip.someplace.net" # Your host running 'vncviewer -listen' 8765 # It could also be your IP number. If it is 8766 # a router/firewall, you will need to 8767 # configure it to redirect port 5500 to you 8768 r 8769 # workstation running 'vncviewer -listen' 8770 8771 dir=/tmp/vnc_helpdesk.$$ # Make a temporary working dir. 8772 mkdir $dir || exit 1 8773 cd $dir || exit 1 8774 8775 trap "cd /tmp; rm -rf $dir" 0 2 15 # Cleans up on exit. 8776 8777 wget $webhost/x11vnc # Fetch x11vnc binary. If multi- 8778 chmod 755 ./x11vnc # platform, use $webhost/`uname`/x11vnc 8779 # or similar. 8780 8781 ./x11vnc -connect_or_exit $vnchost -rfbport 0 -nopw -ssl # Note -ssl option. 8782 8783 with the hostnames or IP addresses customized to your case. 8784 8785 The only change from the "vnc" above is the addition of the -ssl 8786 option to x11vnc. This will create a temporary SSL cert: openssl(1) 8787 will need to be installed on the user's end. A fixed SSL cert file 8788 could be used to avoid this (and provide some authentication; more 8789 info here.) 8790 8791 The naive user will be doing this: 8792 wget -qO - http://www.mysite.com/hd/vncs | sh - 8793 8794 (or perhaps even use https:// if available.) 8795 8796 But before that, the helpdesk operator needs to have "vncviewer 8797 -listen" running as before, however he needs an SSL tunnel at his end. 8798 The easiest way to do this is use Enhanced TightVNC Viewer (SSVNC). 8799 Start it, and select Options -> 'Reverse VNC Connection (-listen)'. 8800 Then UN-select 'Verify All Certs' (this can be enabled later if you 8801 want; you'll need the x11vnc SSL certificate), and click 'Listen'. 8802 8803 If you don't want to use SSVNC for the viewer, but rather set up 8804 STUNNEL manually instead, make a file "stunnel.cfg" containing: 8805 foreground = yes 8806 pid = 8807 8808 [vnc] 8809 accept = 5500 8810 connect = localhost:5501 8811 8812 and run: 8813 stunnel ./stunnel.cfg 8814 8815 and then start the "vncviewer -listen 1" (i.e. 1 to correspond to the 8816 5501 port.) Note that this assumes the stunnel install created a 8817 Server SSL cert+key, usually /etc/stunnel/stunnel.pem (not all distros 8818 will do this.) Also, that file is by default only readable by root, so 8819 stunnel needs to be run as root. If your system does not have a key 8820 installed or you do not want to run stunnel as root (or change the 8821 permissions on the file), you can use x11vnc to create one for you for 8822 example: 8823 x11vnc -sslGenCert server self:mystunnel 8824 8825 answer the prompts with whatever you want; you can take the default 8826 for all of them if you like. The openssl(1) package must be installed. 8827 See this link and this one too for more info on SSL certs. This 8828 creates $HOME/.vnc/certs/server-self:mystunnel.pem, then you would 8829 change the "stunnel.cfg" to look something like: 8830 foreground = yes 8831 pid = 8832 cert = /home/myusername/.vnc/certs/server-self:mystunnel.pem 8833 8834 [vnc] 8835 accept = 5500 8836 connect = localhost:5501 8837 8838 In any event, with stunnel having been setup, the naive user is 8839 instructed to paste in and run: 8840 wget -qO - http://www.mysite.com/hd/vncs | sh - 8841 8842 to pick up the vncs script this time. 8843 8844 Of course if a man-in-the-middle can alter what the user downloads 8845 then all bets are off!. 8846 8847 More SSL variations and info about certificates can be found here. 8848 8849 8850 OpenSSL libssl.so.0.9.7 problems: 8851 8852 If you build your own stunnel or x11vnc for deployment, you may want 8853 to statically link libssl.a and libcrypto.a into it because Linux 8854 distros are currently a bit of a mess regarding which version of 8855 libssl is installed. 8856 8857 You will find the details here. 8858 8859 8860 Q-127: Can I (temporarily) mount my local (viewer-side) Windows/Samba 8861 File share on the machine where x11vnc is running? 8862 8863 You will have to use an external network redirection for this. 8864 Filesystem mounting is not part of the VNC protocol. 8865 8866 We show a simple Samba example here. 8867 8868 First you will need a tunnel to redirect the SMB requests from the 8869 remote machine to the one you sitting at. We use an ssh tunnel: 8870 sitting-here> ssh -C -R 1139:localhost:139 far-away.east 8871 8872 Or one could combine this with the VNC tunnel at the same time, e.g.: 8873 sitting-here> ssh -C -R 1139:localhost:139 -t -L 5900:localhost:5900 far-away 8874 .east 'x11vnc -localhost -display :0' 8875 8876 Port 139 is the Windows Service port. For Windows systems instead of 8877 Samba, you may need to use the actual IP address of the Window machine 8878 instead of "localhost" in the -R option (since the Windows service 8879 does not listen on localhost by default.) 8880 8881 Note that we use 1139 instead of 139 on the remote side because 139 8882 would require root permission to listen on (and you may have a samba 8883 server running on it already.) 8884 8885 The ssh -C is to enable compression, which might speed up the data 8886 transfers. 8887 8888 Depending on the remote system side configuration, it may or may not 8889 be possible to mount the SMB share as a non-root user. Try it first as 8890 a non-root user and if that fails you will have to become root. 8891 8892 We will assume the user name is "fred" and we will try to mount the 8893 viewer-side Windows SMB share "//haystack/pub" in 8894 /home/fred/smb-haystack-pub. 8895 far-away> mkdir -p /home/fred/smb-haystack-pub 8896 far-away> smbmount //haystack/pub /home/fred/smb-haystack-pub -o username=fre 8897 d,ip=127.0.0.1,port=1139 8898 8899 (The 2nd command may need to be run as root.) Then run "df" or "ls -l 8900 /home/fred/smb-haystack-pub" to see if it is mounted properly. Consult 8901 the smbmount(8) and related documentation (it may require some 8902 fiddling to get write permissions correct, etc.) To unmount: 8903 far-away> smbumount /home/fred/smb-haystack-pub 8904 8905 At some point we hope to fold some automation for SMB ssh redir setup 8906 into the Enhanced TightVNC Viewer (SSVNC) package we provide (as of 8907 Sep 2006 it is there for testing.) 8908 8909 8910 Q-128: Can I redirect CUPS print jobs from the remote desktop where 8911 x11vnc is running to a printer on my local (viewer-side) machine? 8912 8913 You will have to use an external network redirection for this. 8914 Printing is not part of the VNC protocol. 8915 8916 We show a simple Unix to Unix CUPS example here. Non-CUPS port 8917 redirections (e.g. LPD) should also be possible, but may be a bit more 8918 tricky. If you are viewing on Windows SMB and don't have a local cups 8919 server it may be trickier still (see below.) 8920 8921 First you will need a tunnel to redirect the print requests from the 8922 remote machine to the one you sitting at. We use an ssh tunnel: 8923 sitting-here> ssh -C -R 6631:localhost:631 far-away.east 8924 8925 Or one could combine this with the VNC tunnel at the same time, e.g.: 8926 sitting-here> ssh -C -R 6631:localhost:631 -t -L 5900:localhost:5900 far-away 8927 .east 'x11vnc -localhost -display :0' 8928 8929 Port 631 is the default CUPS port. The above assumes you have a Cups 8930 server running on your viewer machine (localhost:631), if not, use 8931 something like my-cups-srv:631 (the viewer-side Cups server) in the -R 8932 instead. 8933 8934 Note that we use 6631 instead of 631 on the remote side because 631 8935 would require root permission to listen on (and you likely have a cups 8936 server running on it already.) 8937 8938 Now the tricky part: to get applications to notice your cups 8939 server/printer on localhost:6631. 8940 8941 If you have administrative privilege (i.e. root password) on the 8942 x11vnc side where the desktop is running, it should be easy to add the 8943 printer through some configuration utility (e.g. in KDE: Utilities -> 8944 Printing -> Printing Manager, and then supply admin password, and then 8945 Add Printer/Class, and then fill in the inquisitive wizard. Most 8946 important is the "Remote IPP server" panel where you put in localhost 8947 for Host and 6631 for Port.) The main setting you want to convey is 8948 the host is localhost and the port is non-standard (e.g. 6631.) Some 8949 configuration utilities will take an Internet Printing Protocol (IPP) 8950 URI, e.g. http://localhost:6631/printers/, 8951 ipp://localhost:6631/printers/printer-name, 8952 ipp://localhost:6631/ipp/printer-name, etc. Check your CUPS 8953 documentation and admin interfaces to find what the syntax is and what 8954 the "printer name" is. 8955 8956 If you do not have root or print admin privileges, but are running a 8957 recent (version 1.2 or greater) of the Cups client software, then an 8958 easy way to temporarily switch Cups servers is to create the directory 8959 and file: $HOME/.cups/client.conf on the remote side with a line like: 8960 ServerName localhost:6631 8961 8962 When not using x11vnc for remote access you can comment the above line 8963 out with a '#' (or rename the client.conf file), to have normal cups 8964 operation. 8965 8966 Unfortunately, running applications may need to be restarted to notice 8967 the new printers (libcups does not track changes in client.conf.) 8968 Depending on circumstances, a running application may actually notice 8969 the new printers without restarting (e.g. no print dialog has taken 8970 place yet, or there are no CUPS printers configured on the remote 8971 side.) 8972 8973 Cups client software that is older (1.1) does not support appending 8974 the port number, and for newer ones there is a bug preventing it from 8975 always working (fixed in 1.2.3.) Kludges like these at the command 8976 line will work: 8977 far-away> env CUPS_SERVER=localhost IPP_PORT=6631 lpstat -p -d 8978 far-away> env CUPS_SERVER=localhost IPP_PORT=6631 lpr -P myprinter file.ps 8979 far-away> env CUPS_SERVER=localhost IPP_PORT=6631 firefox 8980 8981 but are somewhat awkward since you have to retroactively set the env. 8982 var IPP_PORT. Its value cannot be broadcast to already running apps 8983 (like the $HOME/.cups/client.conf trick sometimes does.) A common 8984 workaround for an already running app is to somehow get it to "Print 8985 To File", e.g. file.ps and then use something like the lpr example 8986 above. Also, the option "-h host:port" works with CUPS lp(1) and 8987 lpr(1). 8988 8989 You can also print to Windows shares printers in principle. You may do 8990 this with the smbspool(8) command, or configure the remote CUPS via 8991 lpadmin(8), etc, to use a printer URI something like 8992 smb://machine:port/printer (this may have some name resolution 8993 problems WRT localhost.) Also, as with SMB mounting, the port redir 8994 (-R) to the Windows machine must use the actual IP address instead of 8995 "localhost". 8996 8997 At some point we hope to fold some automation for CUPS ssh redir setup 8998 into the Enhanced TightVNC Viewer (SSVNC) package we provide (as of 8999 Sep 2006 it is there for testing.) 9000 9001 9002 Q-129: How can I hear the sound (audio) from the remote applications 9003 on the desktop I am viewing via x11vnc? 9004 9005 You will have to use an external network audio mechanism for this. 9006 Audio is not part of the VNC protocol. 9007 9008 We show a simple Unix to Unix esd example here (artsd should be 9009 possible too, we have also verified the esd Windows port works for the 9010 method described below.) 9011 9012 First you will need a tunnel to redirect the audio from the remote 9013 machine to the one you sitting at. We use an ssh tunnel: 9014 sitting-here> ssh -C -R 16001:localhost:16001 far-away.east 9015 9016 Or one could combine this with the VNC tunnel at the same time, e.g.: 9017 sitting-here> ssh -C -R 16001:localhost:16001 -t -L 5900:localhost:5900 far-a 9018 way.east 'x11vnc -localhost -display :0' 9019 9020 Port 16001 is the default ESD uses. So when an application on the 9021 remote desktop makes a sound it will connect to this tunnel and be 9022 redirected to port 16001 on the local machine (sitting-here in this 9023 example.) The -C option is an attempt to compress the audio a little 9024 bit. 9025 9026 So we next need a local (sitting-here) esd daemon running that will 9027 receive those requests and play them on the local sound device: 9028 sitting-here> esd -promiscuous -port 16001 -tcp -bind 127.0.0.1 9029 9030 See the esd(1) man page for the meaning of the options (the above are 9031 not very secure.) (This method also works with the EsounD windows port 9032 esd.exe) 9033 9034 To test this sound tunnel, we use the esdplay program to play a simple 9035 .wav file: 9036 far-away> esdplay -s localhost:16001 im_so_happy.wav 9037 9038 If you hear the sound (Captain Kirk in this example), that means you 9039 are in great shape. 9040 9041 To run individual audio applications you can use the esddsp(1) 9042 command: 9043 far-away> esddsp -s localhost:16001 xmms 9044 9045 Then you could try playing some sounds inside xmms. You could also set 9046 the environment variable ESPEAKER=localhost:16001 to not need to 9047 supply the -s option all the time. (for reasons not clear, sometimes 9048 esddsp can figure it out on its own.) All the script esddsp does is to 9049 set ESPEAKER and LD_PRELOAD for you so that when the application opens 9050 the sound device (usually /dev/dsp) its interactions with the device 9051 will be intercepted and sent to the esd daemon running on sitting-here 9052 (that in turn writes them to the real, local /dev/dsp.) 9053 9054 Redirecting All sound: 9055 9056 It does not seem to be possible to switch all of the sound of the 9057 remote machine from its sound device to the above esd+ssh tunnel 9058 without some preparation. But it can be done reasonably well if you 9059 prepare (i.e. restart) the desktop with this in mind. 9060 9061 Here is one way to redirect all sound. The idea is we run the entire 9062 desktop with sound directed to localhost:16001. When we are sitting at 9063 far-away.east we run "esd -promiscuous -port 16001 -tcp -bind 9064 127.0.0.1" on far-away.east (to be able to hear the sound.) However, 9065 when we are sitting at sitting-here.west we kill that esd process and 9066 run that same esd command on sitting-here.west and start up the above 9067 ssh tunnel. This is a little awkward, but with some scripts one would 9068 probably kill and restart the esd processes automatically when x11vnc 9069 is used. 9070 9071 So next we have to run the whole desktop pointing toward our esd. Here 9072 is a simple way to test. Log in to the machine via the "FailSafe" 9073 desktop. Then in the lone terminal type something like: 9074 esddsp -s localhost:16001 gnome-session 9075 or: 9076 esddsp -s localhost:16001 startkde 9077 9078 where the last part is whatever command starts your desktop (even 9079 fvwm2.) This causes the environment variables ESPEAKER and LD_PRELOAD 9080 to be set appropriately and every application (processes with the 9081 desktop as an ancestor) will use them. If this scheme works well you 9082 can make it less klunky by adding the command to your ~/.xsession, 9083 etc. file that starts your default desktop. Or you may be able to 9084 configure your desktop to use localhost:16001, or whatever is needed, 9085 via a gui configuration panel. Some Notes: 9086 * Not all audio applications are compatible with the esd and artsd 9087 mechanisms, but many are. 9088 * The audio is not compressed so you probably need a broadband or 9089 faster connection. Listening to music may not be very pleasant... 9090 (Although we found streaming music from across the US over cable 9091 modem worked OK, but took 200 KB/sec, to use less bandwidth 9092 consider something like "ssh far-away.east 'cat favorite.mp3' | 9093 mpg123 -b 4000 -") 9094 * Linux does not seem to have the concept of LD_PRELOAD_64 so if you 9095 run on a mixed 64- and 32-bit ABI system (e.g. AMD x86_64) some of 9096 the applications will fail to run because LD_PRELOAD will point to 9097 libraries of the wrong wordsize. 9098 * At some point we hope to fold some automation for esd or artsd ssh 9099 redir setup into the Enhanced TightVNC Viewer (SSVNC) package we 9100 provide (as of Sep/2006 it is there for testing.) 9101 9102 9103 Q-130: Why don't I hear the "Beeps" in my X session (e.g. when typing 9104 tput bel in an xterm)? 9105 9106 As of Dec/2003 "Beep" XBell events are tracked by default. The X 9107 server must support the XKEYBOARD extension (this is not on by default 9108 in Solaris, see Xserver(1) for how to turn it on via +kb), and so you 9109 won't hear them if the extension is not present. 9110 9111 If you don't want to hear the beeps use the -nobell option. If you 9112 want to hear the audio from the remote applications, consider trying a 9113 redirector such as esd. 9114 9115 9116 Q-131: Does x11vnc work with IPv6? 9117 9118 Update: as of Apr/2010 in the 0.9.10 x11vnc development tarball, there 9119 is now built-in support for IPv6 (128 bit internet addresses.) See the 9120 -6 and -connect options for details. 9121 9122 The remainder of this FAQ entry shows how to do with this with pre 9123 0.9.10 x11vnc using IPv6 helper tools. 9124 _________________________________________________________________ 9125 9126 Using an external IPv6 helper: 9127 A way to do this is via a separate helper program such as inetd (or 9128 for encrypted connections: ssh or stunnel.) For example, you configure 9129 x11vnc to be run from inetd or xinetd and instruct it to listen on an 9130 IPv6 address. For xinetd the setting "flags = IPv6" will be needed. 9131 For inetd.conf, an example is: 9132 5900 stream tcp6 nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc_wrapper.sh 9133 9134 We also provide a transitional tool in "x11vnc/misc/inet6to4" that 9135 acts as a relay for any IPv4 application to allow connections over 9136 IPv6. For example: 9137 inet6to4 5900 localhost:5900 9138 9139 where x11vnc is listening on IPv4 port 5900. 9140 9141 Also note that not all VNC Viewers are IPv6 enabled, so a redirector 9142 may also be needed for them. The tool "inet6to4 -r ..." can do this as 9143 well. SSVNC (see below) supports IPv6 without need for the helper. 9144 9145 # ./inet6to4 -help 9146 9147 inet6to4: Act as an ipv6-to-ipv4 relay for tcp applications that 9148 do not support ipv6. 9149 9150 Usage: inet6to4 9151 inet6to4 -r 9152 9153 Examples: inet6to4 5900 localhost:5900 9154 inet6to4 8080 web1:80 9155 inet6to4 -r 5900 fe80::217:f2ff:fee6:6f5a%eth0:5900 9156 9157 The -r option reverses the direction of translation (e.g. for ipv4 9158 clients that need to connect to ipv6 servers.) Reversing is the default 9159 if this script is named 'inet4to6' (e.g. by a symlink.) 9160 9161 Use Ctrl-C to stop this program. 9162 9163 You can also set env. vars INET6TO4_LOOP=1 or INET6TO4_LOOP=BG 9164 to have an outer loop restarting this program (BG means do that 9165 in the background), and INET6TO4_LOGFILE for a log file. 9166 Also set INET6TO4_VERBOSE to verbosity level and INET6TO4_WAITTIME 9167 and INET6TO4_PIDFILE (see below.) 9168 9169 The "INET6TO4_LOOP=BG" and "INET6TO4_LOGFILE=..." env. variables make 9170 the tool run reliably as a daemon for very long periods. Read the top 9171 part of the script for more information. 9172 _________________________________________________________________ 9173 9174 Encrypted Tunnels with IPv6 Support: 9175 For SSH tunnelled encrypted VNC connections, one can of course use the 9176 IPv6 support in ssh(1). 9177 9178 For SSL encrypted VNC connections, one possibility is to use the IPv6 9179 support in stunnel(1). This includes the built-in support via the 9180 -stunnel option. For example: 9181 x11vnc -stunnel SAVE -env STUNNEL_LISTEN=:: -env STUNNEL_DEBUG=1 ... 9182 _________________________________________________________________ 9183 9184 SSH IPv6 Tricks: 9185 It is interesting to note that ssh(1) can do basically the same thing 9186 as inet6to4 above by: 9187 ssh -g -L 5900:localhost:5901 localhost "printf 'Press Enter to Exit: '; read 9188 x" 9189 9190 (where we have x11vnc running via "-rfbport 5901" in this case.) 9191 9192 Note that one can also make a home-brew SOCKS5 ipv4-to-ipv6 gateway 9193 proxy using ssh like this: 9194 ssh -D '*:1080' localhost "printf 'Press Enter to Exit: '; read x" 9195 9196 then specify a proxy like socks://hostname:1080 where hostname is the 9197 machine running the above ssh command (add -v to ssh for connection 9198 logging info.) 9199 _________________________________________________________________ 9200 9201 IPv6 SSVNC Viewer: 9202 Our SSVNC VNC Viewer is basically a wrapper for ssh(1) and stunnel(1), 9203 and so it already has good IPv6 support because these two commands do. 9204 On Unix, MacOSX, and Windows nearly all of the the remaining parts of 9205 SSVNC (e.g. the built-in proxying and un-encrypted connections) have 9206 been modified to support IPv6 in SSVNC 1.0.26. 9207 9208 9209 9210 9211 9212 9213 Contributions: 9214 9215 Q-132: Thanks for your program or for your help! Can I make a 9216 donation? 9217 9218 Please do (any amount is appreciated; very few have donated) and thank 9219 you for your support! Click on the PayPal button below for more info. 9220 9221 [x-click-but04.gif]-Submit 9222 9223 ======================================================================= 9224 http://www.karlrunge.com/x11vnc/chainingssh.html: 9225 9226 9227 _________________________________________________________________ 9228 9229 Chaining ssh's: Note that for use of a ssh gateway and -L redirection 9230 to an internal host (e.g. "-L 5900:otherhost:5900") the VNC traffic 9231 inside the firewall is not encrypted and you have to manually log into 9232 otherhost to start x11vnc. Kyle Amon shows a method where you chain 9233 two ssh's together that encrypts all network traffic and also 9234 automatically starts up x11vnc on the internal workstation: 9235 #!/bin/sh 9236 # 9237 gateway="example.com" # or "user (a] example.com" 9238 host="labyrinth" # or "user@hostname" 9239 user="kyle" 9240 9241 # Need to sleep long enough for all of the passwords and x11vnc to start up. 9242 # The </dev/null below makes the vncviewer prompt for passwd via popup window. 9243 # 9244 (sleep 10; vncviewer -encodings "copyrect tight zrle zlib hextile" \ 9245 localhost:0 </dev/null >/dev/null) & 9246 9247 # Chain the vnc connection thru 2 ssh's, and connect x11vnc to user's display: 9248 # 9249 exec /usr/bin/ssh -t -L 5900:localhost:5900 $gateway \ 9250 /usr/bin/ssh -t -L 5900:localhost:5900 $host \ 9251 sudo /usr/bin/x11vnc -localhost -auth /home/$user/.Xauthority \ 9252 -rfbauth .vnc/passwd -display :0 9253 9254 Also note the use of sudo(1) to switch to root so that the different 9255 user's .Xauthority file can be accessed. See the visudo(8) manpage for 9256 details on how to set this up (remove the sudo if you do not want to 9257 do this). One can also chain together ssh's for reverse connections 9258 with vncviewers using the -listen option. For this case -R would 9259 replace the -L (and 5500 the 5900, see the #2 example script above). 9260 If the gateway machine's sshd is configured with GatewayPorts=no (the 9261 default) then the double chaining of "ssh -R ..." will be required for 9262 reverse connections to work. 9263 9264 ======================================================================= 9265 http://www.karlrunge.com/x11vnc/miscbuild.html: 9266 9267 9268 _________________________________________________________________ 9269 9270 Misc. Build problems: We collect here rare build problems some users 9271 have reported and the corresponding workarounds. See also the FAQ's on 9272 building. 9273 _________________________________________________________________ 9274 9275 ENV parameter: One user had a problem where the build script below was 9276 failing because his work environment had the ENV variable set to a 9277 script that was resetting his PATH so that gcc could no longer be 9278 found. Make sure you do not have any ENV or BASH_ENV in your 9279 environment doing things like that. Typing "unset ENV", etc. before 9280 configuring and building should clear it. 9281 _________________________________________________________________ 9282 9283 Bash xpg: One user had his bash shell compiled with 9284 --enable-xpg-echo-default that causes some strange behavior with 9285 things like echo "\\1 ..." the configure script executes. In 9286 particular instead of getting "\1" the non-printable character "^A" is 9287 produced, and causes failures at compile time like: 9288 ../rfb/rfbconfig.h:9:22: warning: extra tokens at end of #ifndef directive 9289 9290 The workaround is to configure like this: 9291 env CONFIG_SHELL=/bin/sh /bin/sh ./configure 9292 9293 i.e. avoid using the bash with the misbehavior. A bug has been filed 9294 against autoconf to guard against this. 9295 _________________________________________________________________ 9296 9297 AIX: one user had to add the "X11.adt" package to AIX to get build 9298 header files like XShm.h, etc. 9299 _________________________________________________________________ 9300 9301 Ubuntu Feisty Fawn 7.04: In May/2007 one user said he needed to add 9302 these packages to compile x11vnc on that Linux distro and version: 9303 apt-get install build-essential make bin86 libjpeg62-dev libssl-dev libxtst-d 9304 ev 9305 9306 Note that Ubuntu is based on Debian, so perhaps this is the list 9307 needed on Debian (testing?) as well. To build in Avahi (mDNS service 9308 advertising) support it would appear that libavahi-client-dev is 9309 needed as well. 9310 _________________________________________________________________ 9311 9312 Exceedingly slow compilation: x11vnc has a couple of files which 9313 contain very large "case statements" (over 100 cases) that on some 9314 platforms can take a very long time to compile (in extreme cases over 9315 an hour). However on 32bit Linux with intel/amd processor and gcc 9316 these files usually take less than 10 seconds to compile. For 64bit 9317 systems using gcc the problem appears to be much worse. 9318 9319 The two files with the large number of cases, remote.c and x11vnc.c, 9320 have no real need to be optimized (the code is used only very 9321 infrequently). So it is fine to supply "-O0" (disables optimization) 9322 to CFLAGS when compiling them. However, it is tricky with 9323 autoconf/automake to do this (especially since both the compiler and 9324 make versions have a big effect). 9325 9326 So if the compile times are getting too long for you for these two 9327 files you will need to manually change some things. First, run 9328 configure and when it has finished, edit the generated file 9329 x11vnc/Makefile and put these lines at the very top: 9330 x11vnc-x11vnc.o : CFLAGS += -O0 9331 x11vnc-remote.o : CFLAGS += -O0 9332 9333 Those lines assume gnu make (gmake) is being used. If you are using 9334 another make, say Solaris make, insert these instead: 9335 x11vnc-x11vnc.o := CFLAGS += -O0 9336 x11vnc-remote.o := CFLAGS += -O0 9337 9338 You could write a build shell script that modified the Makefile this 9339 way before running make. 9340 9341 The "-O0" (note it is "capital Oh" followed by "zero") assumes the gcc 9342 compiler. If you are using a different compiler you will need to find 9343 the command line option to disable optimization, or otherwise have the 9344 lines set CFLAGS to the empty string. 9345 _________________________________________________________________ 9346 9347 Broken Thread Local Storage on SuSE 9.2: Starting with x11vnc 0.9.8 9348 the bundled libvncserver uses the __thread keyword to make some of the 9349 encodings (i.e. tight) thread safe (multiple VNC clients can be using 9350 tight at the same time in x11vnc -threads mode.) Evidently on the old 9351 SuSE 9.2 system the compiler does not support the thread local storage 9352 properly. Here is an example build failure: 9353 tight.c:1126: error: unrecognizable insn: 9354 (insn:HI 11 10 13 0 (nil) (set (reg/f:SI 59) 9355 (const:SI (plus:SI (symbol_ref:SI ("%lpalette")) 9356 (const_int 2048 [0x800])))) -1 (nil) 9357 (expr_list:REG_EQUAL (const:SI (plus:SI (symbol_ref:SI ("%lpalette")) 9358 (const_int 2048 [0x800]))) 9359 (nil))) 9360 tight.c:1126: internal compiler error: in extract_insn, at recog.c:2175 9361 Please submit a full bug report, 9362 with preprocessed source if appropriate. 9363 See URL:http://www.suse.de/feedback for instructions. 9364 9365 The workaround is to disable thread local storage at configure time 9366 like this: 9367 env CPPFLAGS="-DTLS=''" ./configure 9368 9369 and then build it. 9370 _________________________________________________________________ 9371 9372 ======================================================================= 9373 http://www.karlrunge.com/x11vnc/sunray.html: 9374 9375 9376 Sun Ray Notes: 9377 9378 You can run x11vnc on your (connected or disconnected) SunRay session 9379 (Please remember to use settings like -wait 200, -sb 15, and not 9380 running a screensaver animation (blank instead) to avoid being a 9381 resource hog! x11vnc does induce a lot of memory I/O from polling the 9382 X server. It also helps to have a solid background color, e.g. 9383 -solid). 9384 9385 News: Sun Ray Remote Control Toolkit: See the nice set of tools in the 9386 Sun Ray Remote Control Toolkit that launch x11vnc automatically for 9387 you for certain usage modes. 9388 9389 You have to know the name of the machine your SunRay session X server 9390 is running on (so you can ssh into it and start x11vnc). You also need 9391 to know the X11 DISPLAY number for the session: on a SunRay it could 9392 be a large number, e.g. :137, since there are many people with X 9393 sessions (Xsun processes) on the same machine. If you don't know it, 9394 you can get it by running who(1) in a shell on the SunRay server and 9395 looking for the dtlocal entry with your username (and if you don't 9396 even know which server machine has your session, you could login to 9397 all possible ones looking at the who output for your username...). 9398 9399 I put some code in my ~/.dtprofile script that stores $DISPLAY 9400 (including the hostname) in a ~/.sunray_current file at session 9401 startup (and deletes it when the X session ends) to make it easy to 9402 get at the hostname and X11 display number info for my current X 9403 sessions when I ssh in and am about to start x11vnc. 9404 9405 SunRay Gotcha #1: Note that even though your SunRay X11 DISPLAY is 9406 something like :137, x11vnc still tries for port 5900 as its listening 9407 port if it can get it, in which case the VNC display (i.e. the 9408 information you supply to the VNC viewer) is something like 9409 sunray-server:0 (note the :0 corresponding to port 5900, it is not 9410 :137). If it cannot get 5900, it tries for 5901, and so on. You can 9411 also try to force the port (and thereby the VNC display) using the 9412 -rfbport NNNN option. 9413 9414 Especially on a busy Sun Ray server it is often difficult to find free 9415 ports for both VNC and the HTTP Java applet server to listen on. This 9416 script, vnc_findports may be of use for doing this automatically. It 9417 suggests x11vnc command line options based on netstat output that 9418 lists the occupied ports. It is even more difficult to start 9419 vncserver/Xvnc on a busy Sun Ray because then 3 ports (HTTP, VNC, and 9420 X11), all separated by 100 are needed! This script, findvncports may 9421 be helpful as well. Both scripts start at VNC display :10 and work 9422 their way up. 9423 9424 SunRay Gotcha #2: If you get an error like: 9425 shmget(tile) failed. 9426 shmget: No space left on device 9427 9428 when starting up x11vnc that most likely means all the shared memory 9429 (shm) slots are filled up on your machine. The Solaris default is only 9430 100, and that can get filled up in a week or so on a SunRay server 9431 with lots of users. If the shm slot is orphaned (e.g. creator process 9432 dies) the slot is not reclaimed. You can view the shm slots with the 9433 "ipcs -mA" command. If there are about 100 then you've probably hit 9434 this problem. They can be cleaned out (by the owner or by root) using 9435 the ipcrm command. I wrote a script shm_clear that finds the orphans 9436 and lists or removes them. Longer term, have your SunRay sysadmin add 9437 something like this to /etc/system: 9438 set shmsys:shminfo_shmmax = 0x2000000 9439 set shmsys:shminfo_shmmni = 0x1000 9440 9441 SunRay Gotcha #3: Some SunRay installations have implemented 9442 suspending certain applications when a SunRay session is in a 9443 disconnected state (e.g. Java Badge pulled out, utdetach, etc). This 9444 is a good thing because it limits hoggy or runaway apps from wasting 9445 the shared CPU resource. Think how much CPU and memory I/O is wasted 9446 by a bunch of Firefox windows running worthless Flash animations while 9447 your session is disconnected! 9448 9449 So some sites have implemented scripts to suspend (e.g. kill -STOP) 9450 certain apps when your badge is removed from the SunRay terminal. When 9451 you reattach, it kill -CONT them. This causes problems for viewing the 9452 detached SunRay session via x11vnc: those suspended apps will not 9453 respond (their windows will be blank or otherwise inactive). 9454 9455 What to do? Well, since you are going to be using the application you 9456 might as well unfreeze it rather than starting up a 2nd instance. Here 9457 is one way to do it using the kill -CONT mechanism: 9458 kill -CONT `ps -ealf | grep ' T ' | grep $LOGNAME | awk '{print $4}'` 9459 9460 If you want to be a good citizen and re-freeze them before you exit 9461 x11vnc this script could be of use: 9462 #!/bin/sh 9463 # 9464 # kill -STOP/-CONT script for x11vnc (or other) SunRay usage ("freezes" 9465 # certain apps from hogging resources when disconnected). 9466 # 9467 # Put here a pattern that matches the apps that are frozen: 9468 # 9469 appmatch="java_vm|jre|netscape-bin|firefox-bin|realplay|acroread|mozilla-bin" 9470 9471 if [ "X$1" = "Xfreeze" ]; then 9472 pkill -STOP -U $LOGNAME "$appmatch" 9473 elif [ "X$1" = "Xthaw" ]; then 9474 pkill -CONT -U $LOGNAME "$appmatch" 9475 9476 elif [ "$RFB_MODE" = "afteraccept" -a "$RFB_STATE" = "NORMAL" ]; then 9477 # a valid x11vnc login. 9478 if [ "$RFB_CLIENT_COUNT" = "1" ]; then 9479 # only one client present. 9480 pkill -CONT -U $LOGNAME "$appmatch" 9481 fi 9482 elif [ "$RFB_MODE" = "gone" -a "$RFB_STATE" = "NORMAL" ]; then 9483 # a valid x11vnc login. 9484 if [ "$RFB_CLIENT_COUNT" = "0" ]; then 9485 # last client present has just left. 9486 pkill -STOP -U $LOGNAME "$appmatch" 9487 fi 9488 fi 9489 exit 0 9490 9491 If you called the script "goodcitizen" you could type "goodcitizen 9492 thaw" to unfreeze them, and then "goodcitizen freeze" to refreeze 9493 them. One could also use these x11vnc options "-afteraccept 9494 goodcitizen -gone goodcitizen" to do it automatically. 9495 9496 SunRay Gotcha #4: Recent versions of the Sun Ray Server Software 9497 SRSS (seems to be version 3.0 or 3.1) have a "misfeature" that when 9498 the session is disconnected (i.e. badge/smartcard out) the screen 9499 locker (xscreensaver) will freeze the X server just when the "Enter 9500 Password" dialog box appears. So you cannot unlock the screen remotely 9501 via x11vnc! 9502 9503 Update: please see Bob Doolittle's detailed description of the this 9504 issue at the bottom of this section. 9505 9506 Here "freeze" means "stop other X clients from inserting keyboard and 9507 mouse input and from viewing the current contents of the screen". Or 9508 something like that; the upshot is x11vnc can't do its normal thing. 9509 9510 There are several workarounds for this. 9511 9512 1) The easiest one by far is to put these lines in your 9513 $HOME/.dtprofile file: 9514 SUN_SUNRAY_UTXLOCK_PREF="/usr/openwin/bin/xlock -mode blank" 9515 export SUN_SUNRAY_UTXLOCK_PREF 9516 9517 One might argue that xlock isn't particularly "pretty". (Just IMHO, 9518 but if something like this not being pretty actually gets in the way 9519 of your work I think some introspection may be in order. :-) 9520 9521 2) The problem has been traced to the pam_sunray.so PAM module. 9522 Evidently xscreensaver invokes this pam module and it communicates 9523 with utsessiond who in turn instructs the Xsun server to not process 9524 any synthetic mouse/keyboard input or to update the screen 9525 framebuffer. It is not clear if this is by design (security?) or 9526 something else. 9527 9528 In any event, the problem can be avoided, somewhat drastically, by 9529 commenting out the corresponding line in /etc/pam.conf: 9530 #xscreensaver auth sufficient /opt/SUNWut/lib/pam_sunray.so syncondisplay 9531 9532 Leave the other xscreensaver pam authentication lines unchanged. The 9533 dtsession-SunRay line may also need to be commented out to avoid the 9534 problem for CDE sessions. N.B. it is possible the application of a 9535 SSRS patch, etc, may re-enable that /etc/pam.conf line. It may be 9536 difficult to convince a sysadmin to make this change. 9537 9538 3) A more forceful way is to kill the xscreensaver process from a 9539 shell prompt whenever you connect via x11vnc and the screen is in a 9540 locked state: 9541 pkill -U $LOGNAME '^xscreensaver$' 9542 9543 And then after you are in be sure to restart it by typing something 9544 like: 9545 xscreensaver & 9546 9547 You may want to avoid restarting it until you are about to disconnect 9548 your VNC viewer (since if it locks the screen while you are working 9549 you'll be stuck again). 9550 9551 3') The above idea can be done a bit more cleanly by having x11vnc do 9552 it. Suppose we called the following script xss_killer: 9553 #!/bin/sh 9554 # 9555 # xss_killer: kill xscreensaver after a valid x11vnc client logs in. 9556 # Restart xscreensaver and lock it when the last client 9557 # disconnects. 9558 9559 PATH=/usr/openwin/bin:/usr/bin:$PATH 9560 export PATH 9561 9562 if [ "$RFB_MODE" = "afteraccept" -a "$RFB_STATE" = "NORMAL" ]; then 9563 # a valid x11vnc login. 9564 if [ "$RFB_CLIENT_COUNT" = "1" ]; then 9565 # only one client present. 9566 pkill -U $LOGNAME '^xscreensaver$' 9567 pkill -KILL -U $LOGNAME -f xscreensaver/hacks 9568 fi 9569 elif [ "$RFB_MODE" = "gone" -a "$RFB_STATE" = "NORMAL" ]; then 9570 # a valid x11vnc login. 9571 if [ "$RFB_CLIENT_COUNT" = "0" ]; then 9572 # last client present has just left. 9573 xscreensaver -nosplash & 9574 sleep 1 9575 xscreensaver-command -lock & 9576 fi 9577 fi 9578 9579 Then we would run x11vnc with these options: "-afteraccept xss_killer 9580 -gone xss_killer". The -afteraccept option (introduced in version 0.8) 9581 is used to run a command after a vncviewer has successfully logged in 9582 (note that this is a VNC login, not a Unix login, so you may not want 9583 to do this if you are really paranoid...) 9584 9585 Note if you use the above script and also plan to Ctrl-C (SIGINT) 9586 x11vnc you have to run the xscreensaver in a new process group to 9587 avoid killing it as well. One way to do this is via this kludge: 9588 perl -e 'setpgrp(0,0); exec "xscreensaver -nosplash &"' 9589 9590 in the above script. 9591 9592 4) There appears to be a bug in pam_sunray.so in that it doesn't seem 9593 to honor the convention that, say, DISPLAY=unix:3 means to use Unix 9594 sockets to connect to display 3 on the local machine (this is a bit 9595 faster than TCP sockets). Rather, it thinks the display is a non-local 9596 one to a machine named "unix" (that usually does not resolve to an IP 9597 address). 9598 9599 Amusingly, this can be used to bypass the pam_sunray.so blocking of 9600 Xsun that prevents one from unlocking the screen remotely via x11vnc. 9601 One could put something like this in $HOME/.dtprofile to kill any 9602 existing xscreensavers and then start up a fresh xscreensaver using 9603 DISPLAY=unix:N 9604 # stop/kill any running xscreensavers (probably not running yet, but to be sure 9605 ) 9606 xscreensaver-command -exit 9607 pkill -U $LOGNAME '^xscreensaver$' 9608 env DISPLAY=`echo $DISPLAY | sed -e 's/^.*:/unix:/'` xscreensaver & 9609 9610 9611 Important: Note that all of the above workarounds side-step the 9612 pam_sunray.so PAM module in one way or another. You'll need to see if 9613 that is appropriate for your site's SunRay / smartcard usage. Also, 9614 these hacks may break other things and so you may want to test various 9615 scenarios carefully. E.g. check corner cases like XDMCP/dtremote, 9616 NSCM, etc. 9617 9618 9619 Update May 2008: Here is a useful description of this issue from Bob 9620 Doolittle who is a developer for Sun Ray at Sun. I don't have the time 9621 to digest and distill it and then adjust the above methods to provide 9622 a clearer description, so I just include below the description he sent 9623 me with the hope that it will help some users: 9624 9625 In SRSS 4.0 and earlier, the purpose of pam_sunray.so in the "auth" 9626 PAM stack of screensavers is to enable NSCM (and, although this is 9627 much less commonly used, "SC", which is configured when 3rd-party 9628 software is installed to allow smartcards to be used as part of the 9629 authentication process) to work. It should have no effect with 9630 smartcards. Currently, however, it does block the PAM stack for all 9631 sessions, which causes xscreensaver, when it locks a disconnected 9632 session, to not process any mouse or keyboard events as you 9633 describe (unless xscreensaver does an X server grab, however, other 9634 applications should still be able to draw in the session although 9635 xscreensaver may be playing tricks like putting a black window on 9636 top of everything). In both of the NSCM and SC models, 9637 authentication occurs in a separate session before SRSS will 9638 reconnect to the user session, in which case pam_sunray.so causes 9639 xscreensaver to just unlock the screen without prompting the user 9640 to enter their password again. To do this, pam_sunray.so has to 9641 block until the session becomes reconnected, so it can query SRSS 9642 at that time to determine whether the user has already 9643 authenticated or not. In SRSS 4.0 and earlier releases, 9644 pam_sunray.so could have been optimized to not block smartcard 9645 sessions, although since the session is disconnected this typically 9646 isn't important (except in the x11vnc case, as you've observed). 9647 9648 In SRSS 4.1, however, for increased security the out-of-session 9649 authentication model has been extended to *all* session types, so 9650 pam_sunray.so will be required in all cases unless users are 9651 willing to authenticate twice upon hotdesking (e.g. when their card 9652 is inserted). In future, we may do away with pam_sunray.so, and in 9653 fact with any traditional screen locker in the user session, since 9654 SRSS itself will be providing better security than a screen locker 9655 running entirely within the user's X session is capable of 9656 providing. 9657 9658 Your trick of setting DISPLAY to unix:DPY will effectively disable 9659 pam_sunray.so (I'm not sure I'd call that a bug - you're going out 9660 of your way to do something that wouldn't occur in the normal 9661 course of events, and really provides no useful value other than to 9662 tickle this behavior in pam_sunray.so). This will mean that, in 9663 SRSS 4.0 and earlier releases, users will be prompted for their 9664 passwords twice when reconnecting to their sessions for NSCM and SC 9665 session types. In 4.1, disabling pam_sunray.so in this way will 9666 cause this double-authentication to occur for *all* sessions, 9667 including simple smartcard sessions. Users may be willing to pay 9668 that price in order to be able to use x11vnc in disconnected 9669 sessions. I like this hack, personally. It's a little less 9670 convenient than some of the other approaches you describe, but it's 9671 lighter-weight and more secure than most of the other approaches, 9672 and provides the value of being able to use x11vnc in locked 9673 sessions. 9674 9675 Here are some other minor notes: - I wouldn't recommend storing 9676 your display in your .dtprofile, unless you're willing to live with 9677 a single session at a time. Personally, I often find myself using 9678 several sessions, in several FoGs, for short periods of time so 9679 this would certainly break. IMO it's pretty easy to use $DISPLAY to 9680 do what you want on the fly, as needed, so I don't think the price 9681 of breaking multiple-session functionality would be worth the 9682 convenience, to me at least. Here's some ksh/bash syntax to extract 9683 the hostname and display number on the fly which you may find 9684 useful: 9685 HOSTNAME=${DISPLAY%:*} 9686 FULLDPY=${DISPLAY#*:} 9687 DPYNUM=${FULLDPY%.*} 9688 9689 A final note may give you some insight into other clever hacks in 9690 this area: - Check out utaction. It's a very handy little utility 9691 that can be run as a daemon in the user session which will invoke a 9692 specified command upon session connects and/or disconnects. 9693 Personally, I start one up in my .dtprofile as follows: 9694 utaction -c $HOME/.srconnectrc -d $HOME/.srdisconnectrc & 9695 9696 This then allows me to construct a .srconnectrc script containing 9697 useful commands I'd like to have run every time I insert my 9698 smartcard, and a .srdisconnectrc script of commands to be run every 9699 time I remove my smartcard (or, connect/disconnect to my session 9700 via NSCM or SC). This can be used for things like notifying a chat 9701 client of away status, as well as some of the hacks you've 9702 described on your page such as freeze/unfreeze, or perhaps to 9703 terminate an xscreensaver and start up a new one with the unix:DPY 9704 $DISPLAY specification as you describe (although it probably makes 9705 most sense to do this at login time, as opposed to every connect or 9706 disconnect event). 9707 9708 ======================================================================= 9709 http://www.karlrunge.com/x11vnc/ssl.html: 9710 9711 9712 _________________________________________________________________ 9713 9714 Notes on x11vnc SSL Certificates and Key Management: 9715 9716 The simplest scheme ("x11vnc -ssl TMP") is where x11vnc generates a 9717 temporary, self-signed certificate each time (automatically using 9718 openssl(1)) and the VNC viewer client accepts the certificate without 9719 question (e.g. user clicks "Yes" in a dialog box. Perhaps the dialog 9720 allows them to view the certificate too). Also note stunnel's default 9721 is to quietly accept all certificates. 9722 9723 The encryption this provides protects against all passive sniffing of 9724 the VNC traffic and passwords on the network and so it is quite good, 9725 but it does not prevent a Man-In-The-Middle active attack: e.g. an 9726 attacker intercepts the VNC client stream and sends it his own Public 9727 key for SSL negotiation (pretending to be the server). Then it makes a 9728 connection to SSL x11vnc itself and forwards the data back and forth. 9729 He can see all the traffic and modify it as well. 9730 9731 Most people don't seem to worry about Man-In-The-Middle attacks these 9732 days; they are more concerned about passive sniffing of passwords, 9733 etc. Perhaps someday that will change if attack tools are used more 9734 widely to perform the attack. NOTE: There are hacker tools like 9735 dsniff/webmitm and cain that implement SSL Man-In-The-Middle attacks. 9736 They all rely on the client not bothering to check that the cert is 9737 valid. 9738 9739 If you are not worried about Man-In-The-Middle attacks you do not have 9740 to read the techniques described in the rest of this document. 9741 9742 To prevent Man-In-The-Middle attacks, certificates must somehow be 9743 verified. This requires the VNC client side have some piece of 9744 information that can be used to verify the SSL x11vnc server. 9745 Alternatively, although rarely done, x11vnc can verify VNC Clients' 9746 certificates, see the -sslverify option that is discussed below. 9747 9748 There are a number of ways to have the client authenticate the SSL 9749 x11vnc server. The quickest way perhaps would be to copy (safely) the 9750 certificate x11vnc prints out: 9751 26/03/2006 21:12:00 Creating a temporary, self-signed PEM certificate... 9752 ... 9753 -----BEGIN CERTIFICATE----- 9754 MIIC4TCCAkqgAwIBAgIJAMnwCaOjvEKaMA0GCSqGSIb3DQEBBAUAMIGmMQswCQYD 9755 VQQGEwJBVTEOMAwGA1UEBxMFTGludXgxITAfBgNVBAsTGGFuZ2VsYS0xMTQzNDI1 9756 NTIwLjQxMTE2OTEPMA0GA1UEChMGeDExdm5jMS4wLAYDVQQDEyV4MTF2bmMtU0VM 9757 (more lines) ... 9758 -----END CERTIFICATE----- 9759 9760 to the client machine(s) and have the client's SSL machinery (e.g. 9761 stunnel, Web Browser, or Java plugin) import the certificate. That way 9762 when the connection to x11vnc is made the client can verify that is it 9763 the desired server on the other side of the SSL connection. 9764 9765 So, for example suppose the user is using the SSL enabled Java VNC 9766 Viewer and has incorporated the x11vnc certificate into his Web 9767 browser on the viewing side. If he gets a dialog that the certificate 9768 is not verified he knows something is wrong. It may be a 9769 Man-In-The-Middle attack, but more likely x11vnc certificate has 9770 changed or expired or his browser was reinstalled and/or lost the 9771 certificate, etc, etc. 9772 9773 As another example, if the user was using stunnel with his VNC viewer 9774 (this is mentioned in this FAQ), e.g. STUNNEL.EXE on Windows, then he 9775 would have to set the "CAfile = path-to-the-cert" and "verify = 2" 9776 options in the stunnel.conf file before starting up the tunnel. If a 9777 x11vnc certificate cannot be verified, stunnel will drop the 9778 connection (and print a failure message in its log file). 9779 9780 A third example, using the VNC viewer on Unix with stunnel the wrapper 9781 script can be used this way: "ss_vncviewer -verify ./x11vnc.crt 9782 far-away.east:0" where ./x11vnc.crt is the copied certificate x11vnc 9783 printed out. 9784 9785 As fourth example, our SSVNC enhanced tightvnc viewer can also use 9786 these certificate files for server authentication. You can load them 9787 via the SSVNC 'Certs...' dialog and set 'ServerCert' to the 9788 certificate file you safely copied there. 9789 9790 Note that in principle the copying of the certificate to the client 9791 machine(s) itself could be altered by a Man-In-The-Middle attack! You 9792 can't win; it is very difficult to be completely secure. It is 9793 unlikely the attacker could predict how you were going to send it 9794 unless you had, say, done it many times before the same way. SSH is a 9795 very good way to send it (but of course it too depends on public keys 9796 being sent unaltered between the two machines!). 9797 9798 If you are really paranoid, I'm sure you'll figure out a really good 9799 way to transport the certificates. See the Certificate Authority 9800 scheme below for a way to make this easier (you just have to do it 9801 once). 9802 9803 _________________________________________________________________ 9804 9805 Saving SSL certificates and keys: 9806 9807 Now, it would be very inconvenient to copy the new temporary 9808 certificate every time x11vnc is run in SSL mode. So for convenience 9809 there is the "SAVE" keyword to instruct x11vnc to save the certificate 9810 it creates: 9811 x11vnc -ssl SAVE -display :0 ... 9812 9813 This behavior is now the default, you must use "TMP" for a temporary 9814 one. It will save the certificate and private key in these files: 9815 ~/.vnc/certs/server.crt 9816 ~/.vnc/certs/server.pem 9817 9818 The ".crt" file contains only the certificate and should be safely 9819 copied to the VNC Viewer machine(s) that will be authenticating the 9820 x11vnc server. The ".pem" file contains both the certificate and the 9821 private key and should be kept secret. (If you don't like the default 9822 location ~/.vnc/certs, e.g. it is on an NFS share and you are worried 9823 about local network sniffing, use the -ssldir dir option to point to a 9824 different directory.) 9825 9826 So the next time you run "x11vnc -ssl SAVE ..." it will read the 9827 server.pem file directly instead of creating a new one. 9828 9829 You can manage multiple SSL x11vnc server keys in this simple way by 9830 using: 9831 x11vnc -ssl SAVE-key2 -display :0 ... 9832 9833 etc, where you put whatever name you choose for the key after "SAVE-". 9834 E.g. "-ssl SAVE-fred". 9835 9836 Also, if you want to be prompted to possibly change the made up names, 9837 etc. that x11vnc creates (e.g. "x11vnc-SELF-SIGNED-CERT-7762" for the 9838 CommonName) for the certificates distinguished name (DN), then use 9839 "x11vnc -ssl SAVE_PROMPT ...", "x11vnc -ssl SAVE_PROMPT-fred ..." etc. 9840 when you create the key the first time. 9841 9842 Tip: when prompting, if you choose the CommonName entry to be the full 9843 internet hostname of the machine the clients will be connecting to 9844 then that will avoid an annoying dialog box in their Web browsers that 9845 warn that the CommonName doesn't match the hostname. 9846 9847 _________________________________________________________________ 9848 9849 Passphrases for server keys: 9850 9851 Well, since now with the "SAVE" keyword the certificate and key will 9852 be longer lived, one can next worry about somebody stealing the 9853 private key and pretending to be the x11vnc server! How to guard 9854 against this? 9855 9856 The first is that the file is created with perms 600 (i.e. -rw-------) 9857 to make it harder for an untrusted user to copy the file. A better way 9858 is to also encrypt the private key with a passphrase. You are prompted 9859 whether you want to do this or not when the key is first created under 9860 "-ssl SAVE" mode ("Protect key with a passphrase? y/n"). It is 9861 suggested that you use a passphrase. The inconvenience is every time 9862 you run "x11vnc -ssl SAVE ..." you will need to supply the passphrase 9863 to access the private key: 9864 06/04/2006 11:39:11 using PEM /home/runge/.vnc/certs/server.pem 0.000s 9865 9866 A passphrase is needed to unlock an OpenSSL private key (PEM file). 9867 Enter passphrase> 9868 9869 before x11vnc can continue. 9870 9871 _________________________________________________________________ 9872 9873 Being your own Certificate Authority: 9874 9875 A very sophisticated way that scales well if the number of users is 9876 large is to use a Certificate Authority (CA) whose public certificate 9877 is available to all of the VNC clients and whose private key has been 9878 used to digitally sign the x11vnc server certificate(s). 9879 9880 The idea is as follows: 9881 * A special CA cert and key is generated. 9882 * Its private key is always protected by a good passphrase since it 9883 is only used for signing. 9884 * The CA cert is (safely) distributed to all machines where VNC 9885 clients will run. 9886 * One or more x11vnc server certs and keys are generated. 9887 * The x11vnc server cert is signed with the CA private key. 9888 * x11vnc is run using the server key. (e.g. "-ssl SAVE") 9889 * VNC clients (viewers) can now authenticate the x11vnc server 9890 because they have the CA certificate. 9891 9892 The advantage is the CA cert only needs to be distributed once to the 9893 various machines, that can be done even before x11vnc server certs are 9894 generated. 9895 9896 As above, it is important the CA private key and the x11vnc server key 9897 are kept secret, otherwise someone could steal them and pretend to be 9898 the CA or the x11vnc server if they copied the key. It is recommended 9899 that the x11vnc server keys are also protected via a passphrase (see 9900 the previous section). 9901 9902 Optionally, VNC viewer certs and keys could also be generated to 9903 enable the x11vnc server to authenticate each client. This is not 9904 normally done (usually a simple viewer password scheme is used), but 9905 this can be useful in some situations. These optional steps go like 9906 this: 9907 * One or more VNC client certs and keys are generated. 9908 * These VNC client certs are signed with the CA private key. 9909 * The VNC client certs+keys are safely distributed to the 9910 corresponding client machines. 9911 * x11vnc is told to verify clients by using the CA cert. (e.g. 9912 "-sslverify CA") 9913 * When VNC clients (viewers) connect, they must authenticate 9914 themselves to x11vnc by using their client key. 9915 9916 Again, it is a good idea if the client private keys are protected with 9917 a passphrase, otherwise if stolen they could be used to gain access to 9918 the x11vnc server. Once distributed to the client machines, there is 9919 no need to keep the client key on the CA machine that generated and 9920 signed it. You can keep the client certs if you like because they are 9921 public. 9922 9923 _________________________________________________________________ 9924 9925 How to do the above CA steps with x11vnc: 9926 9927 Some utility commands are provided to ease the cert+key creation, 9928 signing, and management: -sslGenCA, -sslGenCert, -sslDelCert, 9929 -sslEncKey, -sslCertInfo. They basically run the openssl(1) command 9930 for you to manage the certs/keys. It is required that openssl(1) is 9931 installed on the machine and available in PATH. All commands can be 9932 pointed to an alternate toplevel certificate directory via the -ssldir 9933 option if you don't want to use the default ~/.vnc/certs. 9934 9935 1) To generate your Certificate Authority (CA) cert and key run this: 9936 x11vnc -sslGenCA 9937 9938 Follow the prompts, you can modify any informational strings you care 9939 to. You will also be required to encrypt the CA private key with a 9940 passphrase. This generates these files: 9941 ~/.vnc/certs/CA/cacert.pem (the CA public certificate) 9942 ~/.vnc/certs/CA/private/cakey.pem (the encrypted CA private key) 9943 9944 If you want to use a different directory use -ssldir It must supplied 9945 with all subsequent SSL utility options to point them to the correct 9946 directory. 9947 9948 2) To generate a signed x11vnc server cert and key run this: 9949 x11vnc -sslGenCert server 9950 9951 As with the CA generation, follow the prompts and you can modify any 9952 informational strings that you care to. This will create the files: 9953 ~/.vnc/certs/server.crt (the server public certificate) 9954 ~/.vnc/certs/server.pem (the server private key + public cert) 9955 9956 It is recommended to protect the server private key with a passphrase 9957 (you will be prompted whether you want to). You will need to provide 9958 it whenever you start x11vnc using this key. 9959 9960 3) Start up x11vnc using this server key: 9961 x11vnc -ssl SAVE -display :0 ... 9962 9963 (SAVE corresponds to server.pem, see -sslGenCert server somename info 9964 on creating additional server keys, server-somename.crt ...) 9965 9966 4) Next, safely copy the CA certificate to the VNC viewer (client) 9967 machine(s). Perhaps: 9968 scp ~/.vnc/CA/cacert.pem clientmachine:. 9969 9970 5) Then the tricky part, make it so the SSL VNC Viewer uses this 9971 certificate! There are a number of ways this might be done, it depends 9972 on what your client and/or SSL tunnel is. Some examples: 9973 9974 For the SSL Java VNC viewer supplied with x11vnc in 9975 classes/ssl/VncViewer.jar or classes/ssl/SignedVncViewer.jar: 9976 * Import the cacert.pem cert into your Web Browser (e.g. Edit -> 9977 Preferences -> Privacy & Security -> Manage Certificates -> 9978 WebSites -> Import) 9979 * Or Import the cacert.pem cert into your Java Plugin (e.g. run 9980 ControlPanel, then Security -> Certificates -> Secure Site -> 9981 Import) 9982 9983 When importing, one would give the browser/java-plugin the path to the 9984 copied cacert.pem file in some dialog. Note that the Web browser or 9985 Java plugin is used for the server authentication. If the user gets a 9986 "Site not verified" message while connecting he should investigate 9987 further. 9988 9989 For the use of stunnel (e.g. on Windows) one would add this to the 9990 stunnel.conf: 9991 # stunnel.conf: 9992 client = yes 9993 options = ALL 9994 CAfile = /path/to/cacert.pem # or maybe C:\path\to\cacert.pem 9995 [myvncssl] 9996 accept = 5901 9997 connect = far-away.east:5900 9998 9999 (then point the VNC viewer to localhost:1). 10000 10001 Here is an example for the Unix stunnel wrapper script ss_vncviewer in 10002 our SSVNC package: 10003 ss_vncviewer -verify ./cacert.pem far-away.east:0 10004 10005 Our SSVNC enhanced tightvnc viewer GUI can also use the certificate 10006 file for server authentication. You can load it via the SSVNC 10007 'Certs...' dialog and set 'ServerCert' to the cacert.pem file you 10008 safely copied there. 10009 10010 _________________________________________________________________ 10011 10012 Tricks for server keys: 10013 10014 To create additional x11vnc server keys do something like this: 10015 x11vnc -sslGenCert server myotherkey 10016 10017 and use it this way: 10018 x11vnc -ssl SAVE-myotherkey ... 10019 10020 The files will be ~/.vnc/certs/server-myotherkey.{crt,pem} 10021 10022 You can also create a self-signed server key: 10023 x11vnc -sslGenCert server self:third_key 10024 10025 and use it this way: 10026 x11vnc -ssl SAVE-self:third_key ... 10027 10028 This key is not signed by your CA. This can be handy to have a key set 10029 separate from your CA when you do not want to create a 2nd CA 10030 cert+key. 10031 10032 _________________________________________________________________ 10033 10034 Using external CA's: 10035 10036 You don't have to use your own CA cert+key, you can use a third 10037 party's instead. Perhaps you have a company-wide CA or you can even 10038 have your x11vnc certificate signed by a professional CA (e.g. 10039 www.thawte.com or www.verisign.com or perhaps the free certificate 10040 service www.startcom.org or www.cacert.org). 10041 10042 The advantage to doing this is that the VNC client machines will 10043 already have the CA certificates installed and you don't have to 10044 install it on each machine. 10045 10046 To generate an x11vnc server cert+key this way you should generate a 10047 "request" for a certicate signing something like this (we use the name 10048 "external" in this example, it could be anything you want): 10049 x11vnc -sslGenCert server req:external 10050 10051 This will create the request file: 10052 ~/.vnc/certs/server-req:external.req 10053 10054 Which you should send to the external CA. When you get the signed 10055 certificate back from them, save it in the file: 10056 ~/.vnc/certs/server-req:external.crt 10057 10058 and create the .pem this way: 10059 mv ~/.vnc/certs/server-req:external.key ~/.vnc/certs/server-req:external. 10060 pem 10061 chmod 600 ~/.vnc/certs/server-req:external.pem 10062 cat ~/.vnc/certs/server-req:external.crt >> ~/.vnc/certs/server-req:external. 10063 pem 10064 10065 You also rename the two files (.crt and .pem) to have a shorter 10066 basename if you like. E.g.: 10067 mv ~/.vnc/certs/server-req:external.pem ~/.vnc/certs/server-ext.pem 10068 mv ~/.vnc/certs/server-req:external.crt ~/.vnc/certs/server-ext.crt 10069 10070 and the use via "x11vnc -ssl SAVE-ext ...", etc. 10071 10072 On the viewer side make sure the external CA's certificate is 10073 installed an available for the VNC viewer software you plan to use. 10074 10075 _________________________________________________________________ 10076 10077 Using Client Keys for Authentication: 10078 10079 You can optionally create certs+keys for your VNC client machines as 10080 well. After distributing them to the client machines you can have 10081 x11vnc verify the clients using SSL. Here is how to do this: 10082 10083 x11vnc -sslGenCert client dilbert 10084 x11vnc -sslGenCert client wally 10085 x11vnc -sslGenCert client alice 10086 ... 10087 10088 As usual, follow the prompts if you want to change any of the info 10089 field values. As always, it is a good idea (although inconvenient) to 10090 protect the private keys with a passphrase. These files are created: 10091 ~/.vnc/certs/clients/dilbert.crt 10092 ~/.vnc/certs/clients/dilbert.pem 10093 ... 10094 10095 Note that these are kept in a clients subdirectory. 10096 10097 Next, safely copy the .pem files to each corresponding client machine 10098 and incorporate them into the VNC viewer / SSL software (see the ideas 10099 mentioned above for the CA and server keys). The only difference is 10100 these certificates might be referred to as "My Certificates" or 10101 "Client Certificates". They are used for client authentication (which 10102 is relatively rare for SSL). 10103 10104 After copying them you can delete the clients/*.pem files for extra 10105 safety because the private keys are not needed by the x11vnc server. 10106 You don't really need the clients/*.crt files either (because they 10107 have been signed by the CA). But they could come in handy for tracking 10108 or troubleshooting, etc. 10109 10110 Now start up x11vnc and instruct it to verify connecting clients via 10111 SSL and the CA cert: 10112 x11vnc -ssl SAVE -sslverify CA 10113 10114 The "CA" special token instructs x11vnc to use its CA signed certs for 10115 verification. 10116 10117 For arbitrary self-signed client certificates (no CA) it might be 10118 something like this: 10119 x11vnc -ssl SAVE -sslverify path/to/client.crt 10120 x11vnc -ssl SAVE -sslverify path/to/client-hash-dir 10121 x11vnc -ssl SAVE -sslverify path/to/certs.txt 10122 10123 Where client.crt would be an individual client certificate; 10124 client-hash-dir a directory of file names based on md5 hashes of the 10125 certs (see -sslverify); and certs.txt signifies a single file full of 10126 client certificates. 10127 10128 Finally, connect with your VNC viewer using the key. Here is an 10129 example for the Unix stunnel wrapper script ss_vncviewer: using client 10130 authentication (and the standard server authentication with the CA 10131 cert): 10132 ss_vncviewer -mycert ./dilbert.pem -verify ./cacert.pem far-away.east:0 10133 10134 Our SSVNC enhanced tightvnc viewer can also use these openssl .pem 10135 files (you can load them via Certs... -> MyCert dialog). 10136 10137 It is also possible to use -sslverify on a per-client key basis, and 10138 also using self-signed client keys (x11vnc -sslGenCert client 10139 self:dilbert) 10140 10141 Now a tricky part is to get Web browsers or Java Runtime to import and 10142 use the openssl .pem cert+key files. See the next paragraph on how to 10143 convert them to pkcs12 format. If you find a robust way to import them 10144 and and get them to use the cert please let us know! 10145 10146 Here is how to convert our openssl crt/pem files to pkcs12 format 10147 (contains both the client certificate and key) that can be read by Web 10148 browsers and Java for use in client authentication: 10149 openssl pkcs12 -export -in mycert.crt -inkey mycert.pem -out mycert.p12 10150 10151 it will ask for a passphrase to protect mycert.p12. Some software 10152 (e.g. Java ControlPanel) may require a non-empty passphrase. Actually, 10153 since our .pem contains both the certificate and private key, you 10154 could just supply it for the -in and remove the -inkey option. It 10155 appears that for certificates only importing, our .crt file is 10156 sufficient and can be read by Mozilla/Firefox and Java... 10157 10158 If you have trouble getting your Java Runtime to import and use the 10159 cert+key, there is a workaround for the SSL-enabled Java applet. On 10160 the Web browser URL that retrieves the VNC applet, simply add a 10161 "/?oneTimeKey=..." applet parameter (see ssl-portal for more details 10162 on applet parameters; you don't need to do the full portal setup 10163 though). The value of the oneTimeKey will be the very long string that 10164 is output of the onetimekey program found in the classes/ssl x11vnc 10165 directory. Or you can set oneTimeKey=PROMPT in which case the applet 10166 will ask you to paste in the long string. These scheme is pretty ugly, 10167 but it works. A nice application of it is to make one time keys for 10168 users that have already logged into a secure HTTPS site via password. 10169 A cgi program then makes a one time key for the logged in user to use: 10170 it is passed back over HTTPS as the applet parameter in the URL and so 10171 cannot be sniffed. x11vnc is run to use that key via -sslverify. 10172 10173 Update: as of Apr 2007 in the 0.9.1 x11vnc tarball there is a new 10174 option setting "-users sslpeer=" that will do a switch user much like 10175 -unixpw does, but this time using the emailAddress field of the 10176 Certificate subject of the verified Client. This mode requires 10177 -sslverify turned on to verify the clients via SSL. This mode can be 10178 useful in situations using -create or -svc where a new X server needs 10179 to be started up as the authenticated user (but unlike in -unixpw 10180 mode, the unix username is not obviously known). 10181 10182 _________________________________________________________________ 10183 10184 Revoking Certificates: 10185 10186 A large, scaled-up installation may benefit from being able to revoke 10187 certificates (e.g. suppose a user's laptop with a vnc client or server 10188 key is compromised.) You can use this option with x11vnc: -sslCRL. See 10189 the info at that link for a guide on what openssl(1) commands you will 10190 need to run to revoke a certificate. 10191 10192 _________________________________________________________________ 10193 10194 Additional utlities: 10195 10196 You can get information about your keys via -sslCertInfo. These lists 10197 all your keys: 10198 x11vnc -sslCertInfo list 10199 x11vnc -sslCertInfo ll 10200 10201 (the latter is long format). 10202 10203 These print long output, including the public certificate, for 10204 individual keys: 10205 x11vnc -sslCertInfo server 10206 x11vnc -sslCertInfo dilbert 10207 x11vnc -sslCertInfo all (every key, very long) 10208 10209 If you want to add a protecting passphrase to a key originally created 10210 without one: 10211 x11vnc -sslEncKey SAVE 10212 x11vnc -sslEncKey SAVE-fred 10213 10214 To delete a cert+key: 10215 x11vnc -sslDelCert SAVE 10216 x11vnc -sslDelCert SAVE-fred 10217 x11vnc -sslDelCert wally 10218 10219 (but rm(1) will be just as effective). 10220 10221 _________________________________________________________________ 10222 10223 Chained Certificates: 10224 10225 There is increasing interest in using chained CA's instead of a single 10226 CA. The merits of using chained CA's are not described here besides to 10227 say its use may make some things easier when a certificate needs to be 10228 revoked. 10229 10230 x11vnc supports chained CA certificates. We describe a basic use case 10231 here. 10232 10233 Background: Of course the most straight forward way to use SSL with 10234 x11vnc is to use no CA at all (see above): a self-signed certificate 10235 and key is used and its certificate needs to be safely copied to the 10236 client side. This is basically the same as the SSH style of managing 10237 keys. Next level up, one can use a single CA to sign server keys: then 10238 only the CA's certificate needs to be safely copied to the client 10239 side, this can happen even before any server certs are created (again, 10240 see all of the discussion above.) 10241 10242 With a certificate chain there are two or more CA's involved. Perhaps 10243 it looks like this: 10244 root_CA ---> intermediate_CA ---> server_cert 10245 10246 Where the arrow basically means "signs". 10247 10248 In this usage mode the client (viewer-side) will have root_CA's 10249 certificate available for verifying (and nothing else.) If the viewer 10250 only received server_cert's certificate, it would not have enough info 10251 to verify the server. The client needs to have intermediate_CA's cert 10252 as well. The way to do this with x11vnc (i.e. an OpenSSL using app) is 10253 to concatenate the server_cert's pem and the intermediate_CA's 10254 certificate together. 10255 10256 For example, suppose the file intermediate_CA.crt had 10257 intermediate_CA's certificate. And suppose the file server_cert.pem 10258 had the server's certificate and private key pair as described above 10259 on this page. We need to do this: 10260 cat intermediate_CA.crt >> server_cert.pem 10261 10262 (Note: the order of the items inside the file matters; intermediate_CA 10263 must be after the server key and cert) and then we run x11vnc like 10264 this: 10265 x11vnc -ssl ./server_cert.pem ... 10266 10267 Then, on the VNC viewer client side, the viewer authenticates the 10268 x11vnc server by using root_CA's certificate. Suppose that is in a 10269 file named root_CA.crt, then using the SSVNC wrapper script 10270 ss_vncviewer (which is also included in the SSVNC package) as our 10271 example, we have: 10272 ss_vncviewer -verify ./root_CA.crt hostname:0 10273 10274 (where "hostname" is the machine where x11vnc is running.) One could 10275 also use the SSVNC GUI setting Certs -> ServerCert to the root_CA.crt 10276 file. Any other SSL enabled VNC viewer would use root_CA.crt in a 10277 similar way. 10278 _________________________________________________________________ 10279 10280 Creating Chained Certificates: 10281 10282 Here is a fun example using VeriSign's "Trial Certificate" program. 10283 Note that VeriSign has a Root CA and also an Intermediate CA and uses 10284 the latter to sign customers certificates. So this provides an easy 10285 way to test out the chained certificates mechanism with x11vnc. 10286 10287 First we created a test x11vnc server key: 10288 openssl genrsa -out V1.key 1024 10289 10290 then we created a certificate signing request (CSR) for it: 10291 openssl req -new -key V1.key -out V1.csr 10292 10293 (we followed the prompts and supplied information for the various 10294 fields.) 10295 10296 Then we went to VeriSign's page http://www.verisign.com/ssl/index.html 10297 and clicked on "FREE TRIAL" (the certificate is good for 14 days.) We 10298 filled in the forms and got to the point where it asked for the CSR 10299 and so we pasted in the contents of the above V1.csr file. Then, after 10300 a few more steps, VeriSign signed and emailed us our certificate. 10301 10302 The VeriSign Trial certificates were found here: 10303 http://www.verisign.com/support/verisign-intermediate-ca/Trial_Secure_Server_ 10304 Root/index.html 10305 http://www.verisign.com/support/verisign-intermediate-ca/trial-secure-server- 10306 intermediate/index.html 10307 10308 The former was pasted into a file V-Root.crt and the latter was pasted 10309 into V-Intermediate.crt 10310 10311 We pasted our Trial certificate that VeriSign signed and emailed to us 10312 into a file named V1.crt and then we typed: 10313 cat V1.key V1.crt > V1.pem 10314 cat V1.pem V-Intermediate.crt > V1-combined.pem 10315 chmod 600 V1.pem V1-combined.pem 10316 10317 So now the file V1-combined.pem has our private key and (VeriSign 10318 signed) certificate and VeriSign's Trial Intermediate certificate. 10319 10320 Next, we start x11vnc: 10321 x11vnc -ssl ./V1-combined.pem ... 10322 10323 and finally, on the viewer side (SSVNC wrapper script example): 10324 ss_vncviewer -verify ./V-Root.crt hostname:0 10325 10326 One will find that only that combination of certs and keys will work, 10327 i.e. allow the SSL connection to be established. Every other 10328 combination we tried failed (note that ss_vncviewer uses the external 10329 stunnel command to handle the SSL so we are really testing stunnel's 10330 SSL implementation on the viewer side); and so the system works as 10331 expected. 10332 _________________________________________________________________ 10333 10334 VNC Client Authentication using Certificate Chains: 10335 10336 Now, going the other way around with the client authenticating himself 10337 via this chain of SSL certificates, x11vnc is run this way: 10338 x11vnc -ssl SAVE -sslverify ./V-Root.crt ... 10339 10340 (note since the server must always supply a cert, we use its normal 10341 self-signed, etc., one via "-ssl SAVE" and use the VeriSign root cert 10342 for client authentication via -sslverify. The viewer must now supply 10343 the combined certificates, e.g.: 10344 ss_vncviewer -mycert ./V1-combined.pem hostname:0 10345 _________________________________________________________________ 10346 10347 Using OpenSSL and x11vnc to create Certificate Chains: 10348 10349 Although the x11vnc CA mechanism (-sslGenCA and -sslGenCert; see 10350 above) was designed to only handle a single root CA (to sign server 10351 and/or client certs) it can be coerced into creating a certificate 10352 chain by way of an extra openssl(1) command. 10353 10354 We will first create two CA's via -sslGenCA; then use one of these CA 10355 to sign the other; create a new (non-CA) server cert; and append the 10356 intermediate CA's cert to the server cert to have everything needed in 10357 the one file. 10358 10359 Here are the commands we ran to do what the previous paragraph 10360 outlines. 10361 10362 First we create the two CA's, called CA_root and CA_Intermediate here, 10363 in separate directories via x11vnc: 10364 x11vnc -ssldir ~/CA_Root -sslGenCA 10365 (follow the prompts, we included "CA_Root", e.g. Common Name, to aid ident 10366 ifying it) 10367 10368 x11vnc -ssldir ~/CA_Intermediate -sslGenCA 10369 (follow the prompts, we included "CA_Intermediate", e.g. Common Name, to a 10370 id identifying it) 10371 10372 Next backup CA_Intermediate's cert and then sign it with CA_Root: 10373 mv ~/CA_Intermediate/CA/cacert.pem ~/CA_Intermediate/CA/cacert.pem.ORIG 10374 cd ~/CA_Root 10375 openssl ca -config ./CA/ssl.cnf -policy policy_anything -extensions v3_ca -no 10376 text -ss_cert ~/CA_Intermediate/CA/cacert.pem.ORIG -out ~/CA_Intermediate/CA/ca 10377 cert.pem 10378 10379 Note that it is required to cd to the ~/CA_Root directory and run the 10380 openssl command from there. 10381 10382 You can print out info about the cert you just modified by: 10383 openssl x509 -noout -text -in ~/CA_Intermediate/CA/cacert.pem 10384 10385 Now we create an x11vnc server cert named "test_chain" that is signed 10386 by CA_Intermediate: 10387 x11vnc -ssldir ~/CA_Intermediate -sslGenCert server test_chain 10388 (follow the prompts) 10389 10390 You can print out information about this server cert just created via 10391 this command: 10392 x11vnc -ssldir ~/CA_Intermediate -sslCertInfo SAVE-test_chain 10393 10394 This will tell you the full path to the server certificate, which is 10395 needed because we need to manually append the CA_Intermediate cert for 10396 the chain to work: 10397 cat ~/CA_Intermediate/CA/cacert.pem >> ~/CA_Intermediate/server-test_chain.pe 10398 m 10399 10400 Now we are finally ready to use it. We can run x11vnc using this 10401 server cert+key by either this command: 10402 x11vnc -ssldir ~/CA_Intermediate -ssl SAVE-test_chain ... 10403 10404 or this command: 10405 x11vnc -ssl ~/CA_Intermediate/server-test_chain.pem ... 10406 10407 since they are equivalent (both load the same pem file.) 10408 10409 Finally we connect via VNC viewer that uses CA_Root to verify the 10410 server. As before we use ss_vncviewer: 10411 ss_vncviewer -verify ~/CA_Root/CA/cacert.pem hostname:0 10412 10413 Client Certificates (see above) work in a similar manner. 10414 10415 So although it is a little awkward with the extra steps (e.g. 10416 appending the CA_Intermediate cert) it is possible. If you want to do 10417 this entirely with openssl(1) you will have to learn the openssl 10418 commands corresponding to -genCA and -genCert. You may be able to find 10419 guides on the Internet to do this. Starting with x11vnc 0.9.10, you 10420 can have it print out the wrapper scripts it uses via: -sslScripts 10421 (you will still need to fill in a few pieces of information; ask if it 10422 is not clear from the source code.) 10423 10424 _________________________________________________________________ 10425 10426 More info: 10427 10428 See also this article for some some general info and examples using 10429 stunnel and openssl on Windows with VNC. Also 10430 http://www.stunnel.org/faq/certs.html is a very good source of 10431 information on SSL certificate creation and management. 10432 10433 ======================================================================= 10434 http://www.karlrunge.com/x11vnc/ssl-portal.html: 10435 10436 10437 _________________________________________________________________ 10438 10439 Using Apache as an SSL Gateway to multiple x11vnc servers inside a 10440 firewall: 10441 10442 Background: 10443 10444 The typical way to allow access to x11vnc (or any other VNC server) 10445 running on multiple workstations inside a firewall is via SSH. The 10446 user somewhere out on the Internet logs in to the SSH gateway machine 10447 and uses port forwarding (e.g. ssh -t -L 5900:myworkstation:5900 10448 user@gateway) to set up the encrypted channel that VNC is then 10449 tunneled through. Next he starts up the VNC viewer on the machine 10450 where he is sitting directed to the local tunnel port (e.g. 10451 localhost:0). 10452 10453 The SSH scheme is nice because it is a widely used and well tested 10454 login technique for users connecting to machines inside their company 10455 or home firewall. For VNC access it is a bit awkward, however, because 10456 SSH needs to be installed on the Viewer machine and the user usually 10457 has to rig up his own port redirection plumbing (however, see our 10458 other tool). 10459 10460 Also, some users have restrictive work environments where SSH and 10461 similar applications are prohibited (i.e. only outgoing connections to 10462 standard WWW ports from a browser are allowed, perhaps mediated by a 10463 proxy server). These users have successfully used the method described 10464 here for remote access. 10465 10466 With the SSL support in x11vnc and the SSL enabled Java VNC viewer 10467 applet, a convenient and secure alternative exists that uses the 10468 Apache webserver as a gateway. The idea is that the company or home 10469 internet connection is already running apache as a web server (either 10470 SSL or non-SSL) and we add to it the ability to act as a gateway for 10471 SSL VNC connections. The only thing needed on the Viewer side is a 10472 Java enabled Web Browser: the user simply enters a URL that starts the 10473 entire VNC connection process. No VNC or SSH specific software needs 10474 to be installed on the viewer side machine. 10475 10476 The stunnel VNC viewer stunnel wrapper script provided (ss_vncviewer) 10477 can also take advantage of the method described here with its -proxy 10478 option. 10479 10480 _________________________________________________________________ 10481 10482 Simpler Solutions: This apache SSL VNC portal solution may be too much 10483 for you. It is mainly intended for automatically redirecting to 10484 MULTIPLE workstations inside the firewall. If you only have one or two 10485 inside machines that you want to access, the method described here is 10486 overly complicated! See below for some simpler (and still non-SSH) 10487 encrypted setups. 10488 10489 Also see the recent (Mar/2010) desktop.cgi x11vnc desktop web login 10490 CGI script that achieves much of what the method describes here 10491 (especially if its 'port redirection' feature is enabled.) 10492 _________________________________________________________________ 10493 10494 10495 10496 There are numerous ways to achieve this with Apache. We present one of 10497 the simplest ones here. 10498 10499 Important: these sorts of schemes allow incoming connections from 10500 anywhere on the Internet to fixed ports on machines inside the 10501 firewall. Care must be taken to implement and test thoroughly. If one 10502 is paranoid one can (and should) add extra layers of protection. (e.g. 10503 extra passwords, packet filtering, SSL certificate verification, etc). 10504 10505 Also, it is easy to miss the point that unless precautions are taken 10506 to verify SSL Certificates, then the VNC Viewer is vulnerable to 10507 man-in-the-middle attacks (but not to the more common passive sniffing 10508 attacks). Note that there are hacker tools like dsniff/webmitm and 10509 cain that implement SSL Man-In-The-Middle attacks. They rely on the 10510 client not bothering to check the cert. 10511 _________________________________________________________________ 10512 10513 The Holy Grail: a single https port (443) 10514 10515 Before we discuss the self-contained apache examples here, we want to 10516 mention that many x11vnc users who read this page and implement the 10517 apache SSL VNC portal ask for something that (so far) seems difficult 10518 or impossible to do entirely inside apache: 10519 * A single port, 443 (the default https:// port), is open to the 10520 Internet 10521 * It is HTTPS/SSL encrypted 10522 * It handles both VNC traffic and Java VNC Applet downloads. 10523 * And the server can also serve normal HTTPS webpages, CGI, etc. 10524 10525 It is the last item that makes it tricky (otherwise the method 10526 described on this page will work). If you are interested in such a 10527 solution and are willing to run a separate helper program 10528 (connect_switch) look here. Also, see this apache patch. 10529 _________________________________________________________________ 10530 10531 Example: 10532 10533 The scheme described here sets up apache on the firewall/gateway as a 10534 regular Web proxy into the intranet and allows connections to a single 10535 fixed port on a limited set of machines. 10536 10537 The configuration described in this section does not use the mod_ssl 10538 apache module (the optional configuration described in the section 10539 "Downloading the Java applet to the browser via HTTPS" does take 10540 advantage of mod_ssl) 10541 10542 In this example suppose the gateway machine running apache is named 10543 "www.gateway.east" (e.g. it may also provide normal web service). We 10544 also choose the Internet-facing port for this VNC service to be port 10545 563. One could choose any port, including the default HTTP port 80. 10546 10547 Detail: We choose 563 because it is the rarely used SNEWS port that is 10548 often allowed by Web proxies for the CONNECT method. The idea is the 10549 user may be coming out of another firewall using a proxy (not the one 10550 we describe here, that is, the case when two proxies are involved, 10551 e.g. one at work and another Apache (described here) at home 10552 redirecting into our firewall; the "double proxy" or "double firewall" 10553 problem). Using port 563 simplifies things because CONNECT's to it are 10554 usually allowed by default. 10555 10556 We also assume all of the x11vnc servers on the internal machines are 10557 all listening on port 5915 ("-rfbport 5915") instead of the default 10558 5900. This is to limit any unintended proxy redirections to a lesser 10559 used port, and also to stay out of the way of normal VNC servers on 10560 the same machines. One could obviously implement a scheme that handles 10561 different ports, but we just discuss this simple setup here. 10562 10563 So we basically assume x11vnc has been started this way on all of the 10564 workstations to be granted VNC access: 10565 x11vnc -ssl SAVE -http -display :0 -forever -rfbauth ~/.vnc/passwd -rfbport 5 10566 915 10567 10568 i.e. we force SSL VNC connections, port 5915, serve the Java VNC 10569 viewer applet, and require a VNC password (another option would be 10570 -unixpw). The above command could also be run out of inetd(8). It can 10571 also be used to autodetect the user's display and Xauthority data. 10572 10573 10574 These sections are added to the httpd.conf apache configuration file 10575 on www.gateway.east: 10576 10577 # In the global section you need to enable these modules. 10578 # Note that the ORDER MATTERS! mod_rewrite must be before mod_proxy 10579 # (so that we can check the allowed host list via rewrite) 10580 # 10581 LoadModule rewrite_module modules/mod_rewrite.so 10582 LoadModule proxy_module modules/mod_proxy.so 10583 LoadModule proxy_connect_module modules/mod_proxy_connect.so 10584 LoadModule proxy_ftp_module modules/mod_proxy_ftp.so 10585 LoadModule proxy_http_module modules/mod_proxy_http.so 10586 <IfDefine SSL> 10587 LoadModule ssl_module modules/mod_ssl.so 10588 </IfDefine> 10589 10590 10591 # Near the bottom of httpd.conf you put the port 563 virtual host: 10592 10593 Listen 563 10594 10595 <VirtualHost *:563> 10596 10597 # Allow proxy CONNECT requests *only* to port 5915. 10598 # If the machines use different ports, e.g. 5916 list them here as well: 10599 # 10600 ProxyRequests On 10601 AllowCONNECT 5915 10602 10603 RewriteEngine On 10604 10605 # Convenience rules to expand applet parameters. These do not have a traili 10606 ng "/" 10607 # 10608 # /vnc for http jar file downloading: 10609 # 10610 RewriteRule /vnc/([^/]+)$ /vnc/$1/index.vnc?CONNECT=$1+5915&PO 10611 RT=563&urlPrefix=_2F_vnc_2F_$1 [R,NE,L] 10612 RewriteRule /vnc/trust/([^/]+)$ /vnc/$1/index.vnc?CONNECT=$1+5915&PO 10613 RT=563&urlPrefix=_2F_vnc_2F_$1&trustAllVncCerts=yes [R,NE,L] 10614 RewriteRule /vnc/proxy/([^/]+)$ /vnc/$1/proxy.vnc?CONNECT=$1+5915&PO 10615 RT=563&urlPrefix=_2F_vnc_2F_$1&forceProxy=yes [R,NE,L] 10616 RewriteRule /vnc/trust/proxy/([^/]+)$ /vnc/$1/proxy.vnc?CONNECT=$1+5915&PO 10617 RT=563&urlPrefix=_2F_vnc_2F_$1&forceProxy=yes&trustAllVncCerts=yes [R,NE,L] 10618 10619 # Read in the allowed host to vnc display mapping file. It looks like: 10620 # 10621 # host1 15 10622 # host2 15 10623 # ... 10624 # 10625 # the display "15" means 5815 for http applet download, 5915 for SSL vnc. 10626 # 10627 RewriteMap vnchosts txt:/dist/apache/conf/vnc.hosts 10628 10629 # Proxy: check for the CONNECT hostname and port being in the vnc.hosts list 10630 . 10631 # 10632 RewriteCond %{THE_REQUEST} ^CONNECT [NC] 10633 RewriteCond %{REQUEST_URI} ^(.*):(.*)$ 10634 RewriteCond ${vnchosts:%1|NOTFOUND} NOTFOUND 10635 RewriteRule ^.*$ /VNCFAIL [F,L] 10636 10637 RewriteCond %{THE_REQUEST} ^CONNECT [NC] 10638 RewriteCond %{REQUEST_URI} ^(.*):(.*)$ 10639 RewriteCond 59${vnchosts:%1}=%2 !^(.*)=(\1)$ 10640 RewriteRule ^.*$ /VNCFAIL [F,L] 10641 10642 10643 # Remap /vnc to the proxy http download (e.g. http://host:5815) 10644 # 10645 # First, fail if it starts with the string /vnc0: 10646 # 10647 RewriteRule ^/vnc0.* /VNCFAIL [F,L] 10648 # 10649 # Next, map the prefix to /vnc0/host:protocol:port 10650 # 10651 RewriteRule ^/vnc/([^/]+)/(.*) /vnc0/$1:http:58${vnchosts:$1|NOTFOUND}/$2 10652 [NE] 10653 # 10654 # Drop any not found: 10655 # 10656 RewriteRule ^/vnc0.*NOTFOUND.* /VNCFAIL [F,L] 10657 10658 # Construct the proxy URL and retrieve it: 10659 # 10660 RewriteRule ^/vnc0/([^/]+):([^/]+):([^/]+)/(.*) $2://$1:$3/$4 [P,NE,L] 10661 10662 </VirtualHost> 10663 10664 Then restart apache (perhaps: "apachectl stop; apachectl start"). 10665 10666 Note that the listing of allowed internal workstations is done in an 10667 external file (/dist/apache/conf/vnc.hosts in the example above), the 10668 format is like this: 10669 # allowed vnc hosts file: 10670 hostname1 15 10671 hostname2 15 10672 ... 10673 10674 You list the hostname and the VNC display (always 15 in our example). 10675 Only to these hosts will the external VNC viewers be able to connect 10676 to (via the HTTP CONNECT method). 10677 10678 The above setup requires mod_rewrite and mod_proxy be enabled in the 10679 apache web server. In this example they are loaded as modules (and 10680 note that mod_rewrite must be listed before mod_proxy); 10681 10682 The user at the Java enabled Web browser would simply enter this URL 10683 into the browser: 10684 http://www.gateway.east:563/vnc/host2 10685 10686 to connect to internal workstation host2, etc. 10687 10688 Important: do not put a trailing "/" on the URL, since that will 10689 defeat the RewriteRules that look for the hostname at the very end. 10690 10691 There will be a number of SSL certificate, etc, dialogs he will have 10692 to respond to in addition to any passwords he is required to provide 10693 (this depends on how you set up user authentication for x11vnc). 10694 10695 If a second Web proxy is involved (i.e. the user's browser is inside 10696 another firewall and policy requires using a Web proxy server) then 10697 use this URL: 10698 http://www.gateway.east:563/vnc/proxy/host2 10699 10700 This will involve downloading a signed java viewer applet jar file 10701 that is able to interact with the internal proxy for the VNC 10702 connection. See this FAQ for more info on how this works. Note: 10703 sometimes with the Proxy case if you see 'Bad Gateway' error you will 10704 have to wait 10 or so seconds and then hit reload. This seems to be 10705 due to having to wait for a Connection Keepalive to terminate... 10706 10707 For completeness, the "trust" cases that skip a VNC certificate dialog 10708 (discussed below) would be entered as: 10709 http://www.gateway.east:563/vnc/trust/host2 10710 http://www.gateway.east:563/vnc/trust/proxy/host2 10711 10712 You can of course choose shorter or more easy to remember URL formats. 10713 Just change the Convenience RewriteRules in httpd.conf. 10714 10715 _________________________________________________________________ 10716 10717 Port Variations: 10718 10719 Note that you can run this on the default HTTP port 80 instead of port 10720 563. If you do not expect to have a browser connecting from inside a 10721 proxying firewall (where sometimes only connections to ports 443 and 10722 563 are allowed) this should be fine. Use "80" instead of "563" in the 10723 httpd.conf config file (you may need to merge it with other default 10724 port 80 things you have there). 10725 10726 Then the URL's will be a bit simpler: 10727 http://www.gateway.east/vnc/host2 10728 http://www.gateway.east/vnc/trust/host2 10729 10730 etc. 10731 10732 Besides 80 one could use any other random port number (since there are 10733 so many port scans on 80, a little obscurity might be useful). 10734 10735 One option is to use port "443" (the default https:// port) instead of 10736 "563". In this case Apache is not configured for mod_ssl; we just 10737 happen to use port "443" in the way any random port would be used. 10738 This could be handy if the Viewer side environment is restrictive in 10739 that it only allows outgoing connections to ports 80 and 443 (and, 10740 say, you didn't want to use port 80, or you wanted to use 80 for 10741 something else). Another reason for using 443 would be some web proxy 10742 environments only allow the CONNECT method to go to port 443 (and not 10743 even the case 563 we use above). 10744 10745 _________________________________________________________________ 10746 10747 Details: 10748 10749 Let's go through the httpd.conf additions in detail from the top. 10750 10751 The LoadModules directives load the necessary apache modules. Note 10752 that mod_rewrite must be listed first. If you are compiling from 10753 scratch something like this worked for us: 10754 ./configure --enable-proxy=shared --enable-proxy-connect=shared --enable-ssl= 10755 shared --enable-rewrite=shared --prefix=/dist/apache 10756 10757 Then the VirtualHost *:563 virtual host section starts. 10758 10759 The "ProxyRequests On" and "AllowCONNECT 5915" enable the web server 10760 to forward proxy requests to port 5915 (and only this port) INSIDE the 10761 firewall. Think about the implications of this thoroughly and test it 10762 carefully. 10763 10764 The RewriteRule's are for convenience only so that the URL entered 10765 into the Web browser does not need the various extra parameters, e.g.: 10766 http://www.gateway.east:563/vnc/host2/index.vnc?CONNECT=host2+5915&PORT=563, 10767 blah,blah... 10768 10769 (or otherwise make direct edits to index.vnc to set these parameters). 10770 The forceProxy=yes parameter is passed to the applet to force the use 10771 of a outgoing proxy socket connection. Use it only if the Web browser 10772 is inside a separate Web proxying environment (i.e. large corporation) 10773 10774 The rewrites with parameter urlPrefix are described under Tricks for 10775 Better Response. The "trust" ones (also described under Tricks) with 10776 trustAllVncCerts tell the Java VNC applet to skip a dialog asking 10777 about the VNC Certificate. They are a bit faster and more reliable 10778 than the original method. In the best situation they lead to being 10779 logged in 20 seconds or less (without them the time to login can be 10780 much longer since a number of connections must timeout). 10781 10782 All of the x11vnc Java Viewer applet parameters are described in the 10783 file classes/ssl/README 10784 10785 The external file /dist/apache/conf/vnc.hosts containing the allowed 10786 VNC server hostnames is read in. Its 2nd column contains the VNC 10787 display of the host (always 15 in our example; if you make it vary you 10788 will need to adjust some lines in the httpd.conf accordingly, e.g. 10789 AllowCONNECT). This list is used to constrain both the Jar file 10790 download URL and the proxy CONNECT the VNC viewer makes to only the 10791 intended VNC servers. 10792 10793 Limiting the proxy CONNECT is done with the two sets of RewriteCond 10794 conditions. 10795 10796 Limiting the Jar file download URL is done in the remaining 4 10797 RewriteRule's. 10798 10799 Note that these index.vnc and VncViewer.jar downloads to the browser 10800 are not encrypted via SSL, and so in principle could be tampered with 10801 by a really bad guy. The subsequent VNC connection, however, is 10802 encrypted through a single SSL connection (it makes a CONNECT straight 10803 to x11vnc). See below for how to have these initial downloads 10804 encrypted as well (if the apache web server has SSL/mod_ssl, i.e. 10805 https, enabled and configured). 10806 10807 Unfortunately the Java VNC viewer applet currently is not able to save 10808 its own list of Certificates (e.g. the user says trust this VNC 10809 certificate 'always'). This is because an applet it cannot open local 10810 files, etc. Sadly, the applet cannot even remember certificates in the 10811 same browser session because it is completely reinitialized for each 10812 connection (see below). 10813 10814 _________________________________________________________________ 10815 10816 Too Much? 10817 10818 If these apache rules are a little too much for you, there is a little 10819 bit simpler scheme where you have to list each of the individual 10820 machines in the httpd.conf and ssl.conf files. It may be a little more 10821 typing to maintain, but perhaps being more straight forward (less 10822 RewriteRule's) is desirable. 10823 10824 _________________________________________________________________ 10825 10826 Problems? 10827 10828 To see example x11vnc output for a successful https://host:5900/ 10829 connection with the Java Applet see This Page. 10830 10831 _________________________________________________________________ 10832 10833 Some Ideas for adding extra authentication, etc. for the paranoid: 10834 * VNC passwords: -rfbauth, -passwdfile, or -usepw. Even adding a 10835 simple company-wide VNC password helps block unwanted access. 10836 * Unix passwords: -unixpw 10837 * SSL Client certificates: -sslverify 10838 * Apache AuthUserFile directive: .htaccess, etc. 10839 * Filter connections based on IP address or hostname. 10840 * Use Port-knocking on your firewall as described in: Enhanced 10841 TightVNC Viewer (ssvnc). 10842 * Add proxy password authentication (requires Viewer changes?) 10843 * Run a separate instance of Apache that provides this VNC service 10844 so it can be brought up and down independently of the normal web 10845 server. 10846 * How secure is the Client side? Public machines in internet cafes, 10847 etc, are often hacked, with backdoors and VNC servers of their 10848 own. Prefer using your own firewalled laptop to a public machine. 10849 10850 10851 _________________________________________________________________ 10852 10853 Using non-Java viewers with this scheme: 10854 10855 The ss_vncviewer stunnel wrapper script for VNC viewers has the -proxy 10856 option that can take advantage of this method. 10857 ss_vncviewer -proxy www.gateway.east:563 host1:15 10858 10859 For the case of the "double proxy" situation (see below) supply both 10860 separated by a comma. 10861 ss_vncviewer -proxy proxy1.foobar.com:8080,www.gateway.east:563 host1:15 10862 10863 For the Enhanced TightVNC Viewer (ssvnc) GUI (it uses ss_vncviewer on 10864 Unix) put 'host1:15' into the 'VNC Server' entry box, and here are 10865 possible Proxy/Gateway entries 10866 Proxy/Gateway: www.gateway.east:563 10867 Proxy/Gateway: proxy1.foobar.com:8080,www.gateway.east:563 10868 10869 then click on the 'Connect' button. 10870 10871 _________________________________________________________________ 10872 10873 Downloading the Java applet to the browser via HTTPS: 10874 10875 To have the Java applet downloaded to the user's Web Browser via an 10876 encrypted (and evidently safer) SSL connection the Apache webserver 10877 should be configured for SSL via mod_ssl. 10878 10879 It is actually possible to use the x11vnc Key Management utility 10880 "-sslGenCert" to generate your Apache/SSL .crt and .key files. (In 10881 brief, run something like "x11vnc -sslGenCert server self:apache" then 10882 copy the resulting self:apache.crt file to conf/ssl.crt/server.crt and 10883 extract the private key part from self:apache.pem and paste it into 10884 conf/ssl.key/server.key). Setting the env var REQ_ARGS='-days 1095' 10885 before running x11vnc will bump up the expiration date (3 years in 10886 this case). 10887 10888 Or you can use the standard methods described in the Apache mod_ssl 10889 documentation to create your keys. Then restart Apache, usually 10890 something like "apachectl stop" followed by "apachectl startssl" 10891 10892 In addition to the above sections in httpd.conf one should add the 10893 following to ssl.conf: 10894 SSLProxyEngine On 10895 10896 RewriteEngine On 10897 10898 # Convenience rules to expand applet parameters. These do not have a traili 10899 ng "/" 10900 # 10901 # /vnc http jar file downloading: 10902 # 10903 RewriteRule /vnc/([^/]+)$ /vnc/$1/index.vnc?CONNECT=$ 10904 1+5915&PORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vnc_2F_$1 [R,NE,L] 10905 RewriteRule /vnc/proxy/([^/]+)$ /vnc/$1/proxy.vnc?CONNECT=$ 10906 1+5915&PORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vnc_2F_$1&forceProxy=yes [R,N 10907 E,L] 10908 # 10909 # (we skipped the "trust" ones above, put them in if you like) 10910 # 10911 # /vncs https jar file downloading: 10912 # 10913 RewriteRule /vncs/([^/]+)$ /vncs/$1/index.vnc?CONNECT=$ 10914 1+5915&PORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1 [R,NE,L] 10915 RewriteRule /vncs/proxy/([^/]+)$ /vncs/$1/proxy.vnc?CONNECT=$ 10916 1+5915&PORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&forceProxy=yes [R, 10917 NE,l] 10918 RewriteRule /vncs/trust/([^/]+)$ /vncs/$1/index.vnc?CONNECT=$ 10919 1+5915&PORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&trustAllVncCerts=y 10920 es [R,NE,L] 10921 RewriteRule /vncs/trust/proxy/([^/]+)$ /vncs/$1/proxy.vnc?CONNECT=$ 10922 1+5915&PORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&forceProxy=yes&tru 10923 stAllVncCerts=yes [R,NE,L] 10924 10925 # Convenience rules used for the connect_switch helper (requires Listen 127. 10926 0.0.1:443 above): 10927 # 10928 RewriteRule /vnc443/([^/]+)$ /vncs/$1/index.vnc?CONNECT=$ 10929 1+5915&PORT=443&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1 [R,NE,L] 10930 RewriteRule /vnc443/proxy/([^/]+)$ /vncs/$1/proxy.vnc?CONNECT=$ 10931 1+5915&PORT=443&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&forceProxy=yes [R, 10932 NE,L] 10933 RewriteRule /vnc443/trust/([^/]+)$ /vncs/$1/index.vnc?CONNECT=$ 10934 1+5915&PORT=443&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&trustAllVncCerts=y 10935 es [R,NE,L] 10936 RewriteRule /vnc443/trust/proxy/([^/]+)$ /vncs/$1/proxy.vnc?CONNECT=$ 10937 1+5915&PORT=443&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&forceProxy=yes&tru 10938 stAllVncCerts=yes [R,NE,L] 10939 10940 # Read in the allowed host to vnc display mapping file. It looks like: 10941 # 10942 # host1 15 10943 # host2 15 10944 # ... 10945 # 10946 # the display "15" means 5915 for SSL VNC and 5815 for http applet download. 10947 # 10948 RewriteMap vnchosts txt:/dist/apache/conf/vnc.hosts 10949 10950 10951 # Remap /vnc and /vncs to the proxy http download (e.g. https://host:5915) 10952 # 10953 # First, fail if it starts with the string /vnc0: 10954 # 10955 RewriteRule ^/vnc0.* /VNCFAIL [F,L] 10956 # 10957 # Next, map the prefix to /vnc0:host:protocol:port 10958 # 10959 RewriteRule ^/vnc/([^/]+)/(.*) /vnc0/$1:http:58${vnchosts:$1|NOTFOUND}/$2 10960 [NE] 10961 RewriteRule ^/vncs/([^/]+)/(.*) /vnc0/$1:https:59${vnchosts:$1|NOTFOUND}/$2 10962 [NE] 10963 # 10964 # Drop any not found: 10965 # 10966 RewriteRule ^/vnc0.*NOTFOUND.* /VNCFAIL [F,L] 10967 10968 # Construct the proxy URL and retrieve it: 10969 # 10970 RewriteRule ^/vnc0/([^/]+):([^/]+):([^/]+)/(.*) $2://$1:$3/$4 [P,NE,L] 10971 10972 This is all in the "<VirtualHost _default_:443>" section of ssl.conf. 10973 10974 The user could then point the Web Browser to: 10975 https://www.gateway.east/vnc/host2 10976 10977 or 10978 https://www.gateway.east/vnc/proxy/host2 10979 10980 for the "double proxy" case. (Important: do not put a trailing "/" on 10981 the URL, since that will defeat the RewriteRules.) 10982 10983 As with the httpd.conf case, the external file 10984 (/dist/apache/conf/vnc.hosts in the above example) contains the 10985 hostnames of the allowed VNC servers. 10986 10987 Note that inside the firewall the Java applet download traffic is not 10988 encrypted (only over the Internet is SSL used) for these cases: 10989 https://www.gateway.east/vnc/host2 10990 https://www.gateway.east/vnc/proxy/host2 10991 10992 However for the special "vncs" rules above: 10993 https://www.gateway.east/vncs/host2 10994 10995 the Java applet download is encrypted via SSL for both legs. Note that 10996 the two legs are two separate SSL sessions. So the data is decrypted 10997 inside an apache process and reencrypted by the apache process for the 10998 2nd SSL session inside the same apache process (a very small gap one 10999 might overlook). 11000 11001 The "vncs/trust" ones are like the "trust" ones described earlier 11002 https://www.gateway.east/vncs/trust/mach2 11003 11004 and similarly for the httpsPort ones. See Tricks for Better Response. 11005 11006 In all of the above cases the VNC traffic from Viewer to x11vnc is 11007 encrypted end-to-end in a single SSL session, even for the "double 11008 proxy" case because the CONNECT method is used (there are actually two 11009 CONNECT's for the "double proxy" case). This part (the VNC traffic) is 11010 the most important part to have encrypted. 11011 11012 Note that the Certificate dialogs the user has in his web browser will 11013 be for the Apache Certificate, while for the Java applet it will be 11014 the x11vnc certificate. 11015 11016 Note also that you can have Apache serve up the Jar file VncViewer.jar 11017 and/or index.vnc/proxy.vnc instead of each x11vnc if you want to. 11018 11019 The rules in ssl.conf are similar to the ones in httpd.conf and so are 11020 not discussed in detail. The only really new thing is the /vncs 11021 handling to download the applet jar via HTTPS on port 5915. 11022 11023 The special entries "/vnc443" are only used for the special helper 11024 program (connect_switch) for the https port 443 only mode discussed 11025 here. 11026 11027 _________________________________________________________________ 11028 11029 INETD automation: 11030 11031 The "single-port" (i.e. 5915) HTTPS applet download and VNC connection 11032 aspect shown here is convenient and also enables having x11vnc run out 11033 of inetd. That way x11vnc is run on demand instead of being run all 11034 the time (the user does not have to remember to start it). The first 11035 connections to inetd download index.vnc and the Jar file (via https) 11036 and the the last connection to inetd establishes the SSL VNC 11037 connection. Since x11vnc is restarted for each connection, this will 11038 be a bit slower than the normal process. 11039 11040 For example, the /etc/inetd.conf line could be: 11041 5915 stream tcp nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc_ssl.sh 11042 11043 where the script x11vnc_ssl.sh looks something like this: 11044 #!/bin/sh 11045 11046 /usr/local/bin/x11vnc -inetd -oa /var/log/x11vnc-15.log \ 11047 -ssl SAVE -http -unixpw -localhost \ 11048 -display :0 -auth /home/THE_USER/.Xauthority 11049 11050 where, as usual, the inetd launching needs to know which user is 11051 typically using the display on that machine. One could imagine giving 11052 different users different ports, 5915, 5916, etc. to distinguish (then 11053 the script would need to be passed the username). mod_rewrite could be 11054 used to automatically map username in the URL to his port number. 11055 11056 A better way is to use the "-display WAIT:cmd=FINDDISPLAY" feature to 11057 autodetect the user and Xauthority data: 11058 #!/bin/sh 11059 11060 /usr/local/bin/x11vnc -inetd -oa /var/log/x11vnc-15.log \ 11061 -ssl SAVE -http -unixpw -localhost -users unixpw= \ 11062 -find 11063 11064 (we have used the alias -find for "-display WAIT:cmd=FINDDISPLAY".) 11065 This way the user must supply his Unix username and password and then 11066 his display and Xauthority data on that machine will be located and 11067 returned to x11vnc to allow it to attach. If he doesn't have a display 11068 running on that machine or he fails to log in correctly, the 11069 connection will be dropped. 11070 11071 The variant "-display WAIT:cmd=FINDCREATEDISPLAY" (aliased by 11072 "-create") will actually create a (virtual or real) X server session 11073 for the user if one doesn't already exist. See here for details. 11074 11075 To enable inetd operation for the non-HTTPS Java viewer download (port 11076 5815 in the above httpd.conf example) you will need to run x11vnc in 11077 HTTPONCE mode on port 5815: For example, the /etc/inetd.conf line 11078 could be: 11079 5815 stream tcp nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc \ 11080 -inetd -prog /usr/local/bin/x11vnc -oa /var/log/x11vnc-15.log \ 11081 -http_ssl -display WAIT:cmd=HTTPONCE 11082 11083 where the long inetd.conf line has been split. Note how the -http_ssl 11084 tries to automatically find the .../classes/ssl subdirectory. This 11085 requires the -prog option available in x11vnc 0.8.4 (a shell script 11086 wrapper, e.g. /usr/local/bin/x11vnc_http.sh can be used to work around 11087 this). 11088 11089 Also note the use of "-ssl SAVE" above. This way a saved server.pem is 11090 used for each inetd invocation (rather generating a new one each time 11091 as happens for "-ssl TMP"). Note that it cannot have a protecting 11092 passphrase because inetd will not be able to supply it. 11093 11094 Another option is: 11095 5815 stream tcp nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc \ 11096 -inetd -httpdir /usr/local/share/x11vnc/classes/ssl \ 11097 -oa /var/log/x11vnc-15.log -display WAIT:cmd=HTTPONCE 11098 11099 (this also requires a feature found in x11vnc 0.8.4). 11100 _________________________________________________________________ 11101 11102 Other Ideas: 11103 11104 - The above schemes work, but they are a bit complicated with all of 11105 the rigging. There should be more elegant ways to configure Apache to 11106 do these, but we have not found them (please let us know if you 11107 discover something nice). However, once this scheme has been set up 11108 and is working it is easy to maintain and add/delete workstations, 11109 etc. 11110 11111 - In general Apache is not required, but it makes things convenient. 11112 The firewall itself could do the port redirection via its firewall 11113 rules. Evidently different Internet-facing ports would be required for 11114 each workstation. This could be set up using iptables rules for 11115 example. If there were just one or two machines this would be the 11116 easiest method. For example: 11117 iptables -t nat -A PREROUTING -p tcp -d 24.35.46.57 --dport 5901 -j DNAT --to 11118 -destination 192.168.1.2:5915 11119 iptables -t nat -A PREROUTING -p tcp -d 24.35.46.57 --dport 5902 -j DNAT --to 11120 -destination 192.168.1.3:5915 11121 11122 Where 24.35.46.57 is the internet IP address of the gateway. In this 11123 example 24.35.46.57:5901 is redirected to the internal machine 11124 192.168.1.2:5915 and 24.35.46.57:5902 is redirected to another 11125 internal machine 192.168.1.3:5915, both running x11vnc -ssl ... in SSL 11126 mode. For this example, the user would point the web browser to, e.g.: 11127 https://24.35.46.57:5901/?PORT=5901 11128 11129 or using the stunnel wrapper script: 11130 ss_vncviewer 24.35.46.57:1 11131 11132 One can achieve similar things with dedicated firewall/routers (e.g. 11133 Linksys) using the device's web or other interface to configure the 11134 firewall. 11135 11136 If the user may be coming out of a firewall using a proxy it may be 11137 better to redirect ports 443 and 563 (instead of 5901 and 5902) to the 11138 internal machines so that the user's proxy will allow CONNECTing to 11139 them. 11140 11141 - The redirection could also be done at the application level using a 11142 TCP redirect program (e.g. ip_relay or fancier ones). Evidently more 11143 careful internal hostname checking, etc., could be performed by the 11144 special purpose application to add security. See connect_switch which 11145 is somewhat related. 11146 11147 - One might imagine the ProxyPass could be done for the VNC traffic as 11148 well (for the ssl.conf case) to avoid the CONNECT proxying completely 11149 (which would be nice to avoid). Unfortunately we were not able to get 11150 this to work. Since HTTP is a request-response protocol (as opposed to 11151 a full bidirectional link required by VNC that CONNECT provides) this 11152 makes it difficult to do. It may be possible, but we haven't found out 11153 how yet. 11154 11155 All of the x11vnc Java Viewer applet parameters are described in the 11156 file classes/ssl/README 11157 11158 _________________________________________________________________ 11159 11160 Tricks for Better Response and reliability: 11161 11162 The "original scheme" using httpd.conf and ssl.conf rewrites without 11163 urlPrefix and trustAllVncCerts above should work OK, but may lead to 11164 slow and/or unreliable loading of the applet and final connection to 11165 x11vnc. The following are what I do now to get better response and 11166 reliability. YMMV. 11167 11168 The problem with the "original scheme" is that there is a point where 11169 the VNC Viewer applet can try up to 3 times to retrieve the x11vnc 11170 certificate, since it needs to get it to show it to you and ask you if 11171 you accept it. This can add about 45 seconds to the whole process 11172 (which takes 1 to 1.5 minutes with all the dialogs) since a couple of 11173 those connections must time out. The "trust" items in the config add a 11174 parameter trustAllVncCerts=yes similar to the forceProxy=yes 11175 parameter. This can cut the total time to the VNC password prompt down 11176 to 15 seconds which is pretty good. (Note by ignoring the certificate 11177 this does not protect against man-in-the-middle attacks which are 11178 rare, but maybe the won't be so rare in the future... see 11179 dsniff/webmitm and cain) 11180 11181 First make sure the x11vnc SSL certificate+key is the same as 11182 Apache's. (otherwise you may get one extra dialog and/or one extra 11183 connection that has to time out). 11184 11185 The following RewriteRule's are the same now advocated in the 11186 instructions above. 11187 11188 The httpsPort and urlPrefix= parameters give hints to the applet to 11189 improve connecting: This is what goes in httpd.conf: 11190 RewriteEngine On 11191 RewriteRule /vnc/([^/]+)$ /vnc/$1/index.vnc?CONNECT=$1+5915&PO 11192 RT=563&urlPrefix=_2F_vnc_2F_$1 [R,NE] 11193 RewriteRule /vnc/trust/([^/]+)$ /vnc/$1/index.vnc?CONNECT=$1+5915&PO 11194 RT=563&urlPrefix=_2F_vnc_2F_$1&trustAllVncCerts=yes [R,NE] 11195 RewriteRule /vnc/proxy/([^/]+)$ /vnc/$1/proxy.vnc?CONNECT=$1+5915&PO 11196 RT=563&urlPrefix=_2F_vnc_2F_$1&forceProxy=yes [R,NE] 11197 RewriteRule /vnc/trust/proxy/([^/]+)$ /vnc/$1/proxy.vnc?CONNECT=$1+5915&PO 11198 RT=563&urlPrefix=_2F_vnc_2F_$1&forceProxy=yes&trustAllVncCerts=yes [R,NE] 11199 11200 The httpsPort and urlPrefix provide useful hints to the VNC Viewer 11201 applet when it connects to x11vnc to glean information about Proxies, 11202 certificates, etc. 11203 11204 This is what goes into ssl.conf: 11205 RewriteEngine On 11206 RewriteRule /vnc/([^/]+)$ /vnc/$1/index.vnc?CONNECT=$1+5915&P 11207 ORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vnc_2F_$1 [R,NE] 11208 RewriteRule /vnc/proxy/([^/]+)$ /vnc/$1/proxy.vnc?CONNECT=$1+5915&P 11209 ORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vnc_2F_$1&forceProxy=yes [R,NE] 11210 RewriteRule /vncs/([^/]+)$ /vncs/$1/index.vnc?CONNECT=$1+5915&P 11211 ORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1 [R,NE] 11212 RewriteRule /vncs/proxy/([^/]+)$ /vncs/$1/proxy.vnc?CONNECT=$1+5915&P 11213 ORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&forceProxy=yes [R,NE] 11214 RewriteRule /vncs/trust/([^/]+)$ /vncs/$1/index.vnc?CONNECT=$1+5915&P 11215 ORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&trustAllVncCerts=yes [R,NE 11216 ] 11217 RewriteRule /vncs/trust/proxy/([^/]+)$ /vncs/$1/proxy.vnc?CONNECT=$1+5915&P 11218 ORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&forceProxy=yes&trustAllVnc 11219 Certs=yes [R,NE] 11220 11221 The rest is the same. 11222 11223 The httpsPort and urlPrefix and GET provide useful hints to the VNC 11224 Viewer applet when it connects to x11vnc to glean information about 11225 Proxies, certificates, etc, and also for the ultimate VNC connection 11226 (GET speeds this up by sending a special HTTP GET to cause x11vnc to 11227 immediately switch to the VNC protocol). 11228 11229 To turn these into URLs, as was done above, take the string in the 11230 RewriteRule, e.g. /vncs and turn it into 11231 https://gateway/vncs/machinename Similarly for non-https: 11232 http://gateway:563/vnc/machinename 11233 11234 If you use the 'trust' ones, you are performing NO checks, visual or 11235 otherwise, on the VNC SSL certificate. It is trusted without question. 11236 This speeds things up because it avoids a dialog about certificates, 11237 but of course has some risk WRT Man in the Middle attacks. I don't 11238 recommend them. It is better to use /vnc or /vncs and the first time 11239 you connect carefully check the Certificate and then tell your Browser 11240 and Java Virtual Machine to trust the certificate 'Always'. Then if 11241 you later get an unexpected dialog, you know something is wrong. 11242 Nearly always it is just a changed or expired certificate, but better 11243 safe than sorry... 11244 11245 ======================================================================= 11246 http://www.karlrunge.com/x11vnc/enhanced_tightvnc_viewer.html: 11247 11248 11249 _________________________________________________________________ 11250 11251 Enhanced TightVNC Viewer (SSVNC: SSL/SSH VNC viewer) 11252 11253 (To Downloads) (To Quick Start) 11254 11255 [ssvnc.gif] [ssvnc_windows.gif] [ssvnc_macosx.gif] . . 11256 11257 11258 The Enhanced TightVNC Viewer, SSVNC, adds encryption security to VNC 11259 connections. 11260 11261 The package provides a GUI for Windows, Mac OS X, and Unix that 11262 automatically starts up an STUNNEL SSL tunnel for SSL or ssh/plink for 11263 SSH connections to any VNC server, such as x11vnc, and then launches 11264 the VNC Viewer to use the encrypted tunnel. 11265 11266 The x11vnc server has built-in SSL support, however SSVNC can make SSL 11267 encrypted VNC connections to any VNC Server if they are running an SSL 11268 tunnel, such as STUNNEL or socat, at their end. SSVNC's SSH tunnel 11269 will work to any VNC Server host running sshd that you can log into. 11270 11271 The Enhanced TightVNC Viewer package started as a project to add some 11272 patches to the long neglected Unix TightVNC Viewer. However, now the 11273 front-end GUI, encryption, and wrapper scripts features possibly 11274 outweigh the Unix TightVNC Viewer improvements (see the lists below to 11275 compare). 11276 11277 The SSVNC Unix vncviewer can also be run without the SSVNC encryption 11278 GUI as an enhanced replacement for the xvncviewer, xtightvncviewer, 11279 etc., viewers. 11280 11281 In addition to normal SSL, SSVNC also supports the VeNCrypt SSL/TLS 11282 and Vino/ANONTLS encryption extensions to VNC on Unix, Mac OS X, and 11283 Windows. Via the provided SSVNC VeNCrypt bridge, VeNCrypt and ANONTLS 11284 encryption also works with any third party VNC Viewer (e.g. RealVNC, 11285 TightVNC, UltraVNC, etc...) you select via 'Change VNC Viewer'. 11286 11287 The short name for this project is "ssvnc" for SSL/SSH VNC Viewer. 11288 This is the name of the command to start it. 11289 11290 There is a simplified SSH-Only mode (sshvnc). And an even more 11291 simplified Terminal-Services mode (tsvnc) for use with x11vnc on the 11292 remote side. 11293 11294 The tool has many additional features; see the descriptions below. 11295 11296 It is a self-contained bundle, you could carry it around on, say, a 11297 USB memory stick / flash drive for secure VNC viewing from almost any 11298 machine, Unix, Mac OS X, and Windows (and if you create a directory 11299 named "Home" in the toplevel ssvnc directory on the drive your VNC 11300 profiles and certs will be kept there as well). For Unix, there is 11301 also a conventional source tarball to build and install in the normal 11302 way and not use a pre-built bundle. 11303 11304 _________________________________________________________________ 11305 11306 Announcements: 11307 11308 Important: If you created any SSL certificates with SSVNC (or anything 11309 else) on a Debian or Ubuntu system from Sept. 2006 through May 2008, 11310 then those keys are likely extremely weak and can be easily cracked. 11311 The certificate files should be deleted and recreated on a non-Debian 11312 system or an updated one. See 11313 http://www.debian.org/security/2008/dsa-1571 for details. The same 11314 applies to SSH keys. 11315 11316 Please read this information on using SSVNC on workstations with 11317 Untrusted Local Users. 11318 11319 _________________________________________________________________ 11320 11321 Feature List: 11322 11323 Wrapper scripts and a tcl/tk GUI were written to create these features 11324 for Unix, Mac OS X, and Windows: 11325 * SSL support for connections using the bundled stunnel program. 11326 * Automatic SSH connections from the GUI (system ssh is used on Unix 11327 and MacOS X; bundled plink is used on Windows) 11328 * Ability to Save and Load VNC profiles for different hosts. 11329 * You can also use your own VNC Viewer, e.g. UltraVNC or RealVNC, 11330 with the SSVNC encryption GUI front-end if you prefer. 11331 * Create or Import SSL Certificates and Private Keys. 11332 * Reverse (viewer listening) VNC connections via SSL and SSH. 11333 * VeNCrypt SSL/TLS VNC encryption support (used by VeNCrypt, QEMU, 11334 ggi, libvirt/virt-manager/xen, vinagre/gvncviewer/gtk-vnc) 11335 * ANONTLS SSL/TLS VNC encryption support (used by Vino) 11336 * VeNCrypt and ANONTLS are also enabled for any 3rd party VNC Viewer 11337 (e.g. RealVNC, TightVNC, UltraVNC ...) on Unix, MacOSX, and 11338 Windows via the provided SSVNC VeNCrypt Viewer Bridge tool (use 11339 'Change VNC Viewer' to select the one you want.) 11340 * Support for Web Proxies, SOCKS Proxies, and the UltraVNC repeater 11341 proxy (e.g. repeater://host:port+ID:1234). Multiple proxies may be 11342 chained together (3 max). 11343 * Support for SSH Gateway connections and non-standard SSH ports. 11344 * Automatic Service tunnelling via SSH for CUPS and SMB Printing, 11345 ESD/ARTSD Audio, and SMB (Windows/Samba) filesystem mounting. 11346 * Sets up any additional SSH port redirections that you want. 11347 * Zeroconf (aka Bonjour) is used on Unix and Mac OS X to find VNC 11348 servers on your local network if the avahi-browse or dns-sd 11349 program is available and in your PATH. 11350 * Port Knocking for "closed port" SSH/SSL connections. In addition 11351 to a simple fixed port sequence and one-time-pad implementation, a 11352 hook is also provided to run any port knocking client before 11353 connecting. 11354 * Support for native MacOS X usage with bundled Chicken of the VNC 11355 viewer (the Unix X11 viewer is also provided for MacOS X, and is 11356 better IMHO. It is now the default on MacOS X.) 11357 * Dynamic VNC Server Port determination and redirection (using ssh's 11358 builtin SOCKS proxy, ssh -D) for servers like x11vnc that print 11359 out PORT= at startup. 11360 * Unix Username and Password entry for use with "x11vnc -unixpw" 11361 type login dialogs. 11362 * Simplified mode launched by command "sshvnc" that is SSH Only. 11363 * Simplified mode launched by command "tsvnc" that provides a VNC 11364 "Terminal Services" mode (uses x11vnc on the remote side). 11365 * IPv6 support for all connection modes on Unix, MacOSX, and 11366 Windows. 11367 11368 Patches to TightVNC 1.3.9 vnc_unixsrc tree were created for Unix 11369 TightVNC Viewer improvements (these only apply to the Unix VNC viewer, 11370 including MacOSX XQuartz): 11371 * rfbNewFBSize VNC support (dynamic screen resizing) 11372 * Client-side Scaling of the Desktop in the viewer. 11373 * ZRLE VNC encoding support (RealVNC's encoding) 11374 * Support for the ZYWRLE encoding, a wavelet based extension to ZRLE 11375 to improve compression of motion video and photo regions. 11376 * TurboVNC support (VirtualGL's modified TightVNC encoding; requires 11377 TurboJPEG library) 11378 * Pipelined Updates of the framebuffer as in TurboVNC (asks for the 11379 next update before the current one has finished downloading; this 11380 gives some speedup on high latency connections.) 11381 * Cursor alphablending with x11vnc at 32bpp (-alpha option) 11382 * Option "-unixpw ..." for use with "x11vnc -unixpw" type login 11383 dialogs. 11384 * Support for UltraVNC extensions: 1/n Server side scaling, Text 11385 Chat, Single Window, Disable Server-side Input. Both UltraVNC and 11386 x11vnc servers support these extensions. 11387 * UltraVNC File Transfer via an auxiliary Java helper program (java 11388 must be in $PATH). Note that the x11vnc server also supports 11389 UltraVNC file transfer. 11390 * Connection support for the UltraVNC repeater proxy (-repeater 11391 option). 11392 * Support for UltraVNC Single Click operation. (both unencrypted: SC 11393 I, and SSL encrypted: SC III) 11394 * Support for UltraVNC DSM Encryption Plugin symmetric encryption 11395 mode. (ARC4, AESV2, MSRC4, and SecureVNC) 11396 * Support for UltraVNC MS-Logon authentication (NOTE: the UltraVNC 11397 MS-Logon key exchange implementation is very weak; an eavesdropper 11398 on the network can recover your Windows password easily in a few 11399 seconds; you need to use an additional encrypted tunnel with 11400 MS-Logon.) 11401 * Support for symmetric encryption (including blowfish and 3des 11402 ciphers) to Non-UltraVNC Servers. Any server using the same 11403 encryption method will work, e.g.: x11vnc -enc blowfish:./my.key 11404 * Instead of hostname:display one can also supply "exec=command 11405 args..." to connect the viewer to the stdio of an external command 11406 (e.g. stunnel or socat) rather than using a TCP/IP socket. Unix 11407 domain sockets, e.g. /path/to/unix/socket, and a previously opened 11408 file descriptor fd=0, work too. 11409 * Local Port Protections for STUNNEL and SSH: avoid having for long 11410 periods of time a listening port on the the local (VNC viewer) 11411 side that redirects to the remote side. 11412 * Reverse (viewer listening) VNC connections can show a Popup dialog 11413 asking whether to accept the connection or not (-acceptpopup.) The 11414 extra info provided by UltraVNC Single Click reverse connections 11415 is also supported (-acceptpopupsc) 11416 * Extremely low color modes: 64 and 8 colors in 8bpp 11417 (-use64/-bgr222, -use8/-bgr111) 11418 * Medium color mode: 16bpp mode on a 32bpp Viewer display 11419 (-16bpp/-bgr565) 11420 * For use with x11vnc's client-side caching -ncache method use the 11421 cropping option -ycrop n. This will "hide" the large pixel buffer 11422 cache below the actual display. Set to the actual height or use -1 11423 for autodetection (also, tall screens, H > 2*W, are autodetected 11424 by default). 11425 * Escape Keys: specify a set of modifier keys so that when they are 11426 all pressed down you can invoke Popup menu actions via keystrokes. 11427 I.e., a set of 'Hot Keys'. One can also pan (move) the desktop 11428 inside the viewport via Arrow keys or a mouse drag. 11429 * Scrollbar width setting: -sbwidth n, the default is very thin, 2 11430 pixels, for less distracting -ycrop usage. 11431 * Selection text sending and receiving can be fine-tuned with the 11432 -sendclipboard, -sendalways, and -recvtext options. 11433 * TightVNC compression and quality levels are automatically set 11434 based on observed network latency (n.b. not bandwidth.) 11435 * Improvements to the Popup menu, all of these can now be changed 11436 dynamically via the menu: ViewOnly, Toggle Bell, CursorShape 11437 updates, X11 Cursor, Cursor Alphablending, Toggle Tight/ZRLE, 11438 Toggle JPEG, FullColor/16bpp/8bpp (256/64/8 colors), Greyscale for 11439 low color modes, Scaling the Viewer resolution, Escape Keys, 11440 Pipeline Updates, and others, including UltraVNC extensions. 11441 * Maintains its own BackingStore if the X server does not. 11442 * The default for localhost:0 connections is not raw encoding since 11443 same-machine connections are pretty rare. Default assumes you are 11444 using a SSL or SSH tunnel. Use -rawlocal to revert. 11445 * XGrabServer support for fullscreen mode, for old window managers 11446 (-grab/-graball option). 11447 * Fix for Popup menu positioning for old window managers (-popupfix 11448 option). 11449 * The VNC Viewer ssvncviewer supports IPv6 natively (no helpers 11450 needed.) 11451 11452 The list of 3rd party software bundled in the archive files: 11453 * TightVNC Viewer (windows, unix, macosx) 11454 * Chicken of the VNC Viewer (macosx) 11455 * Stunnel (windows, unix, macosx) 11456 * Putty/Plink/Pageant (windows) 11457 * OpenSSL (windows) 11458 * esound (windows) 11459 11460 These are all self-contained in the bundle directory: they will not be 11461 installed on your system. Just un-zip or un-tar the file you 11462 downloaded and run the frontend ssvnc straight from its directory. 11463 Alternatively, on Unix you can use the conventional source tarball. 11464 11465 _________________________________________________________________ 11466 11467 Here is the Quick Start info from the README for how to setup and use 11468 SSVNC: 11469 Quick Start: 11470 ----------- 11471 11472 Unix and Mac OS X: 11473 11474 Inside a Terminal do something like the following. 11475 11476 Unpack the archive: 11477 11478 % gzip -dc ssvnc-1.0.29.tar.gz | tar xvf - 11479 11480 Run the GUI: 11481 11482 % ./ssvnc/Unix/ssvnc (for Unix) 11483 11484 % ./ssvnc/MacOSX/ssvnc (for Mac OS X) 11485 11486 The smaller file "ssvnc_no_windows-1.0.29.tar.gz" 11487 could have been used as well. 11488 11489 On MacOSX you could also click on the SSVNC app icon in the Finder. 11490 11491 On MacOSX if you don't like the Chicken of the VNC (e.g. no local 11492 cursors, no screen size rescaling, and no password prompting), and you 11493 have the XDarwin X server installed, you can set DISPLAY before starting 11494 ssvnc (or type DISPLAY=... in Host:Disp and hit Return). Then our 11495 enhanced TightVNC viewer will be used instead of COTVNC. 11496 Update: there is now a 'Use X11 vncviewer on MacOSX' under Options ... 11497 11498 11499 If you want a SSH-only tool (without the distractions of SSL) run 11500 the command: 11501 11502 sshvnc 11503 11504 instead of "ssvnc". Or click "SSH-Only Mode" under Options. 11505 Control-h will toggle between the two modes. 11506 11507 11508 If you want a simple VNC Terminal Services only mode (requires x11vnc 11509 on the remote server) run the command: 11510 11511 tsvnc 11512 11513 instead of "ssvnc". Or click "Terminal Services" under Options. 11514 Control-t will toggle between the two modes. 11515 11516 "tsvnc profile-name" and "tsvnc user@hostname" work too. 11517 11518 11519 Unix/MacOSX Install: 11520 11521 There is no standard install for the bundles, but you can make 11522 symlinks like so: 11523 11524 cd /a/directory/in/PATH 11525 ln -s /path/to/ssvnc/bin/{s,t}* . 11526 11527 Or put /path/to/ssvnc/bin, /path/to/ssvnc/Unix, or /path/to/ssvnc/MacOSX 11528 in your PATH. 11529 11530 For the conventional source tarball it will compile and install, e.g.: 11531 11532 gzip -dc ssvnc-1.0.29.src.tar.gz | tar xvf - 11533 cd ssvnc-1.0.29 11534 make config 11535 make all 11536 make PREFIX=/my/install/dir install 11537 11538 then have /my/install/dir/bin in your PATH. 11539 11540 11541 11542 Windows: 11543 11544 Unzip, using WinZip or a similar utility, the zip file: 11545 11546 ssvnc-1.0.29.zip 11547 11548 Run the GUI, e.g.: 11549 11550 Start -> Run -> Browse 11551 11552 and then navigate to 11553 11554 .../ssvnc/Windows/ssvnc.exe 11555 11556 select Open, and then OK to launch it. 11557 11558 The smaller file "ssvnc_windows_only-1.0.29.zip" 11559 could have been used as well. 11560 11561 You can make a Windows shortcut to this program if you want to. 11562 11563 See the Windows/README.txt for more info. 11564 11565 11566 If you want a SSH-only tool (without the distractions of SSL) run 11567 the command: 11568 11569 sshvnc.bat 11570 11571 Or click "SSH-Only Mode" under Options. 11572 11573 11574 If you want a simple VNC Terminal Services only mode (requires x11vnc 11575 on the remote server) run the command: 11576 11577 tsvnc.bat 11578 11579 Or click "Terminal Services" under Options. Control-t will toggle 11580 between the two modes. "tsvnc profile-name" and "tsvnc user@hostname" 11581 work too. 11582 11583 _________________________________________________________________ 11584 11585 You can read all of the SSVNC GUI's Online Help Text here. 11586 _________________________________________________________________ 11587 11588 The bundle unpacks a directory/folder named: ssvnc. It contains these 11589 programs to launch the GUI: 11590 Windows/ssvnc.exe for Windows 11591 MacOSX/ssvnc for Mac OS X 11592 Unix/ssvnc for Unix 11593 11594 (the Mac OS X and Unix launchers are simply links to the bin 11595 directory). See the README for more information. 11596 11597 The SSH-Only mode launcher program has name sshvnc. The Terminal 11598 Services mode launcher program (assumes x11vnc 0.8.4 or later and Xvfb 11599 installed on the server machine) has name tsvnc. 11600 11601 The Viewer SSL support is done via a wrapper script (bin/ssvnc_cmd 11602 that calls bin/util/ss_vncviewer) that starts up the STUNNEL tunnel 11603 first and then starts the TightVNC viewer pointed at that tunnel. The 11604 bin/ssvnc program is a GUI front-end to that script. See this FAQ for 11605 more details on SSL tunnelling. In SSH connection mode, the wrappers 11606 start up SSH appropriately. 11607 11608 11609 Memory Stick Usage: If you create a directory named "Home" in that 11610 toplevel ssvnc directory then that will be used as the base for 11611 storing VNC profiles and certificates. Also, for convenience, if you 11612 first run the command with "." as an argument (e.g. "ssvnc .") it will 11613 automatically create the "Home" directory for you. This is handy if 11614 you want to place SSVNC on a USB flash drive that you carry around for 11615 mobile use and you want the profiles you create to stay with the drive 11616 (otherwise you'd have to browse to the drive directory each time you 11617 load or save). 11618 11619 One user on Windows created a BAT file to launch SSVNC and needed to 11620 do this to get the Home directory correct: 11621 cd \ssvnc\Windows 11622 start \ssvnc\Windows\ssvnc.exe 11623 11624 (an optional profile name can be supplied to the ssvnc.exe line) 11625 11626 WARNING: if you use ssvnc from an "Internet Cafe", i.e. some untrusted 11627 computer, please be aware that someone may have set up that machine to 11628 be capturing your keystrokes, etc. 11629 11630 11631 SSH-Only version: The command "sshvnc" can be run instead of "ssvnc" 11632 to get an SSH-only version of the tool: 11633 11634 [sshvnc.gif] 11635 11636 These also work: "sshvnc myprofile" and "sshvnc user@hostname". To 11637 switch from the regular SSVNC mode, click "SSH-Only Mode" under 11638 Options. This mode is less distracting if you never plan to use SSL, 11639 manage certificates, etc. 11640 11641 11642 Terminal Services Only: The command "tsvnc" can be run instead of 11643 "ssvnc" to get a "Terminal Services" only version of the tool: 11644 11645 [tsvnc.gif] 11646 11647 These also work: "tsvnc myprofile" and "tsvnc user@hostname". To 11648 switch from the regular SSVNC mode, click "Terminal Services" under 11649 Options. 11650 11651 This mode requires x11vnc (0.9.3 or later) installed on the remote 11652 machine to find, create, and manage the user sessions. SSH is used to 11653 create the encrypted and authenticated tunnel. The Xvfb (virtual 11654 framebuffer X server) program must also be installed on the remote 11655 system. However tsvnc will also connect to a real X session (i.e. on 11656 the physical hardware) if you are already logged into the X session; 11657 this is a useful access mode and does not require Xvfb on the remote 11658 system. 11659 11660 This mode should be very easy for beginner users to understand and 11661 use. On the remote end you only need to have x11vnc and Xvfb available 11662 in $PATH, and on the local end you just run something like: 11663 tsvnc myname (a] myhost.com 11664 11665 (or start up the tsvnc GUI first and then enter myname (a] myhost.com and 11666 press "Connect"). 11667 11668 Normally the Terminal Services sessions created are virtual (RAM-only) 11669 ones (e.g. Xvfb, Xdummy, or Xvnc), however a nice feature is if you 11670 have a regular X session (i.e displaying on the physical hardware) on 11671 the remote machine that you are ALREADY logged into, then the x11vnc 11672 run from tsvnc will find it for you as well. 11673 11674 Also, there is setting "X Login" under Advanced Options that allows 11675 you to attach to a real X server with no one logged in yet (i.e. 11676 XDM/GDM/KDM Login Greeter screen) as long as you have sudo(1) 11677 permission on the remote machine. 11678 11679 Nice features to soon to be added to the tsvnc mode are easy CUPS 11680 printing (working fairly well) and Sound redirection (needs much work) 11681 of the Terminal Services Desktop session. It is easier in tsvnc mode 11682 because the entire desktop session can be started with the correct 11683 environment. ssvnc tries to handle the general case of an already 11684 started desktop and that is more difficult. 11685 11686 11687 Proxies: Web proxies, SOCKS proxies, and the UltraVNC repeater proxy 11688 are supported to allow the SSVNC connection to go through the proxy to 11689 the otherwise unreachable VNC Server. SSH gateway machines can be used 11690 in the same way. Read more about SSVNC proxy support here. 11691 11692 11693 Dynamic VNC Server Port determination: If you are running SSVNC on 11694 Unix and are using SSH to start the remote VNC server and the VNC 11695 server prints out the line "PORT=NNNN" to indicate which dynamic port 11696 it is using (x11vnc does this), then if you prefix the SSH command 11697 with "PORT=" SSVNC will watch for the PORT=NNNN line and uses ssh's 11698 built in SOCKS proxy (ssh -D ...) to connect to the dynamic VNC server 11699 port through the SSH tunnel. For example: 11700 VNC Host:Display user (a] somehost.com 11701 Remote SSH Command: PORT= x11vnc -find 11702 11703 or "PORT= x11vnc -display :0 -localhost", etc. Or use "P= x11vnc ..." 11704 11705 There is also code to detect the display of the regular Unix 11706 vncserver(1). It extracts the display (and hence port) from the lines 11707 "New 'X' desktop is hostname:4" and also "VNC server is already 11708 running as :4". So you can use something like: 11709 PORT= vncserver; sleep 15 11710 or: PORT= vncserver :4; sleep 15 11711 11712 the latter is preferred because when you reconnect with it will find 11713 the already running one. The former one will keep creating new X 11714 sessions if called repeatedly. 11715 11716 If you use PORT= on Windows, a large random port is selected instead 11717 and the -rfbport option is passed to x11vnc (it does not work with 11718 vncserver). 11719 11720 11721 11722 Patches for Unix Tightvnc viewer: 11723 11724 The rfbNewFBSize support allows the enhanced TightVNC Unix viewer to 11725 resize when the server does (e.g. "x11vnc -R scale=3/4" remote control 11726 command). 11727 11728 The cursor alphablending is described here. 11729 11730 The RealVNC ZRLE encoding is supported, in addition to some low colors 11731 modes (16bpp and 8bpp at 256, 64, and even 8 colors, for use on very 11732 slow connections). Greyscales are also enabled for the low color 11733 modes. 11734 11735 The Popup menu (F8) is enhanced with the ability to change many things 11736 on the fly. F9 is added as a shortcut to toggle FullScreen mode. 11737 11738 Client Side Caching: The x11vnc client-side caching is handled nicely 11739 by this viewer. The very large pixel cache below the actual display in 11740 this caching method is distracting. Our Unix VNC viewer will 11741 automatically try to autodetect the actual display height if the 11742 framebuffer is very tall (more than twice as high as it is wide). One 11743 can also set the height to the known value via -ycrop n, or use -ycrop 11744 -1 to force autodection. In fullscreen mode one is not possible to 11745 scroll down to the pixel cache region. In non-fullscreen mode the 11746 window manager frame is "shrink-wrapped" around the actual screen 11747 display. You can still scroll down to the pixel cache region. The 11748 scrollbars are set to be very thin (2 pixels) to be less distracting. 11749 Use the -sbwidth n to make them wider. 11750 11751 Probably nobody is interested in the grabserver patch for old window 11752 managers when the viewer is in fullscreen mode... This and some other 11753 unfixed bugs have been fixed in our patches (fullscreen toggle works 11754 with KDE, -x11cursor has been fixed, and the dot cursor has been made 11755 smaller). 11756 11757 From the -help output: 11758 SSVNC Viewer (based on TightVNC viewer version 1.3.9) 11759 11760 Usage: vncviewer [<OPTIONS>] [<HOST>][:<DISPLAY#>] 11761 vncviewer [<OPTIONS>] [<HOST>][::<PORT#>] 11762 vncviewer [<OPTIONS>] exec=[CMD ARGS...] 11763 vncviewer [<OPTIONS>] fd=n 11764 vncviewer [<OPTIONS>] /path/to/unix/socket 11765 vncviewer [<OPTIONS>] -listen [<DISPLAY#>] 11766 vncviewer -help 11767 11768 <OPTIONS> are standard Xt options, or: 11769 -via <GATEWAY> 11770 -shared (set by default) 11771 -noshared 11772 -viewonly 11773 -fullscreen 11774 -noraiseonbeep 11775 -passwd <PASSWD-FILENAME> (standard VNC authentication) 11776 -user <USERNAME> (Unix login authentication) 11777 -encodings <ENCODING-LIST> (e.g. "tight,copyrect") 11778 -bgr233 11779 -owncmap 11780 -truecolour 11781 -depth <DEPTH> 11782 -compresslevel <COMPRESS-VALUE> (0..9: 0-fast, 9-best) 11783 -quality <JPEG-QUALITY-VALUE> (0..9: 0-low, 9-high) 11784 -nojpeg 11785 -nocursorshape 11786 -x11cursor 11787 -autopass 11788 11789 Option names may be abbreviated, e.g. -bgr instead of -bgr233. 11790 See the manual page for more information. 11791 11792 11793 Enhanced TightVNC viewer (SSVNC) options: 11794 11795 URL http://www.karlrunge.com/x11vnc/ssvnc.html 11796 11797 Note: ZRLE and ZYWRLE encodings are now supported. 11798 11799 Note: F9 is shortcut to Toggle FullScreen mode. 11800 11801 Note: In -listen mode set the env var. SSVNC_MULTIPLE_LISTEN=1 11802 to allow more than one incoming VNC server at a time. 11803 This is the same as -multilisten described below. Set 11804 SSVNC_MULTIPLE_LISTEN=MAX:n to allow no more than "n" 11805 simultaneous reverse connections. 11806 11807 Note: If the host:port is specified as "exec=command args..." 11808 then instead of making a TCP/IP socket connection to the 11809 remote VNC server, "command args..." is executed and the 11810 viewer is attached to its stdio. This enables tunnelling 11811 established via an external command, e.g. an stunnel(8) 11812 that does not involve a listening socket. This mode does 11813 not work for -listen reverse connections. 11814 11815 If the host:port is specified as "fd=n" then it is assumed 11816 n is an already opened file descriptor to the socket. (i.e 11817 the parent did fork+exec) 11818 11819 If the host:port contains a '/' it is interpreted as a 11820 unix-domain socket (AF_LOCAL insead of AF_INET) 11821 11822 -multilisten As in -listen (reverse connection listening) except 11823 allow more than one incoming VNC server to be connected 11824 at a time. The default for -listen of only one at a 11825 time tries to play it safe by not allowing anyone on 11826 the network to put (many) desktops on your screen over 11827 a long window of time. Use -multilisten for no limit. 11828 11829 -acceptpopup In -listen (reverse connection listening) mode when 11830 a reverse VNC connection comes in show a popup asking 11831 whether to Accept or Reject the connection. The IP 11832 address of the connecting host is shown. Same as 11833 setting the env. var. SSVNC_ACCEPT_POPUP=1. 11834 11835 -acceptpopupsc As in -acceptpopup except assume UltraVNC Single 11836 Click (SC) server. Retrieve User and ComputerName 11837 info from UltraVNC Server and display in the Popup. 11838 11839 -use64 In -bgr233 mode, use 64 colors instead of 256. 11840 -bgr222 Same as -use64. 11841 11842 -use8 In -bgr233 mode, use 8 colors instead of 256. 11843 -bgr111 Same as -use8. 11844 11845 -16bpp If the vnc viewer X display is depth 24 at 32bpp 11846 request a 16bpp format from the VNC server to cut 11847 network traffic by up to 2X, then tranlate the 11848 pixels to 32bpp locally. 11849 -bgr565 Same as -16bpp. 11850 11851 -grey Use a grey scale for the 16- and 8-bpp modes. 11852 11853 -alpha Use alphablending transparency for local cursors 11854 requires: x11vnc server, both client and server 11855 must be 32bpp and same endianness. 11856 11857 -scale str Scale the desktop locally. The string "str" can 11858 a floating point ratio, e.g. "0.9", or a fraction, 11859 e.g. "3/4", or WxH, e.g. 1280x1024. Use "fit" 11860 to fit in the current screen size. Use "auto" to 11861 fit in the window size. "str" can also be set by 11862 the env. var. SSVNC_SCALE. 11863 11864 If you observe mouse trail painting errors, enable 11865 X11 Cursor mode (either via Popup or -x11cursor.) 11866 11867 Note that scaling is done in software and so can be 11868 slow and requires more memory. Some speedup Tips: 11869 11870 ZRLE is faster than Tight in this mode. When 11871 scaling is first detected, the encoding will 11872 be automatically switched to ZRLE. Use the 11873 Popup menu if you want to go back to Tight. 11874 Set SSVNC_PRESERVE_ENCODING=1 to disable this. 11875 11876 Use a solid background on the remote side. 11877 (e.g. manually or via x11vnc -solid ...) 11878 11879 If the remote server is x11vnc, try client 11880 side caching: x11vnc -ncache 10 ... 11881 11882 -ycrop n Only show the top n rows of the framebuffer. For 11883 use with x11vnc -ncache client caching option 11884 to help "hide" the pixel cache region. 11885 Use a negative value (e.g. -1) for autodetection. 11886 Autodetection will always take place if the remote 11887 fb height is more than 2 times the width. 11888 11889 -sbwidth n Scrollbar width for x11vnc -ncache mode (-ycrop), 11890 default is very narrow: 2 pixels, it is narrow to 11891 avoid distraction in -ycrop mode. 11892 11893 -nobell Disable bell. 11894 11895 -rawlocal Prefer raw encoding for localhost, default is 11896 no, i.e. assumes you have a SSH tunnel instead. 11897 11898 -notty Try to avoid using the terminal for interactive 11899 responses: use windows for messages and prompting 11900 instead. Messages will also be printed to terminal. 11901 11902 -sendclipboard Send the X CLIPBOARD selection (i.e. Ctrl+C, 11903 Ctrl+V) instead of the X PRIMARY selection (mouse 11904 select and middle button paste.) 11905 11906 -sendalways Whenever the mouse enters the VNC viewer main 11907 window, send the selection to the VNC server even if 11908 it has not changed. This is like the Xt resource 11909 translation SelectionToVNC(always) 11910 11911 -recvtext str When cut text is received from the VNC server, 11912 ssvncviewer will set both the X PRIMARY and the 11913 X CLIPBOARD local selections. To control which 11914 is set, specify 'str' as 'primary', 'clipboard', 11915 or 'both' (the default.) 11916 11917 -graball Grab the entire X server when in fullscreen mode, 11918 needed by some old window managers like fvwm2. 11919 11920 -popupfix Warp the popup back to the pointer position, 11921 needed by some old window managers like fvwm2. 11922 -sendclipboard Send the X CLIPBOARD selection (i.e. Ctrl+C, 11923 Ctrl+V) instead of the X PRIMARY selection (mouse 11924 select and middle button paste.) 11925 11926 -sendalways Whenever the mouse enters the VNC viewer main 11927 window, send the selection to the VNC server even if 11928 it has not changed. This is like the Xt resource 11929 translation SelectionToVNC(always) 11930 11931 -recvtext str When cut text is received from the VNC server, 11932 ssvncviewer will set both the X PRIMARY and the 11933 X CLIPBOARD local selections. To control which 11934 is set, specify 'str' as 'primary', 'clipboard', 11935 or 'both' (the default.) 11936 11937 -graball Grab the entire X server when in fullscreen mode, 11938 needed by some old window managers like fvwm2. 11939 11940 -popupfix Warp the popup back to the pointer position, 11941 needed by some old window managers like fvwm2. 11942 11943 -grabkbd Grab the X keyboard when in fullscreen mode, 11944 needed by some window managers. Same as -grabkeyboard. 11945 -grabkbd is the default, use -nograbkbd to disable. 11946 11947 -bs, -nobs Whether or not to use X server Backingstore for the 11948 main viewer window. The default is to not, mainly 11949 because most Linux, etc, systems X servers disable 11950 *all* Backingstore by default. To re-enable it put 11951 11952 Option "Backingstore" 11953 11954 in the Device section of /etc/X11/xorg.conf. 11955 In -bs mode with no X server backingstore, whenever an 11956 area of the screen is re-exposed it must go out to the 11957 VNC server to retrieve the pixels. This is too slow. 11958 11959 In -nobs mode, memory is allocated by the viewer to 11960 provide its own backing of the main viewer window. This 11961 actually makes some activities faster (changes in large 11962 regions) but can appear to "flash" too much. 11963 11964 -noshm Disable use of MIT shared memory extension (not recommended 11965 ) 11966 11967 -termchat Do the UltraVNC chat in the terminal vncviewer is in 11968 instead of in an independent window. 11969 11970 -unixpw str Useful for logging into x11vnc in -unixpw mode. "str" is a 11971 string that allows many ways to enter the Unix Username 11972 and Unix Password. These characters: username, newline, 11973 password, newline are sent to the VNC server after any VNC 11974 authentication has taken place. Under x11vnc they are 11975 used for the -unixpw login. Other VNC servers could do 11976 something similar. 11977 11978 You can also indicate "str" via the environment 11979 variable SSVNC_UNIXPW. 11980 11981 Note that the Escape key is actually sent first to tell 11982 x11vnc to not echo the Unix Username back to the VNC 11983 viewer. Set SSVNC_UNIXPW_NOESC=1 to override this. 11984 11985 If str is ".", then you are prompted at the command line 11986 for the username and password in the normal way. If str is 11987 "-" the stdin is read via getpass(3) for username@password. 11988 Otherwise if str is a file, it is opened and the first line 11989 read is taken as the Unix username and the 2nd as the 11990 password. If str prefixed by "rm:" the file is removed 11991 after reading. Otherwise, if str has a "@" character, 11992 it is taken as username@password. Otherwise, the program 11993 exits with an error. Got all that? 11994 11995 -repeater str This is for use with UltraVNC repeater proxy described 11996 here: http://www.uvnc.com/addons/repeater.html. The "str" 11997 is the ID string to be sent to the repeater. E.g. ID:1234 11998 It can also be the hostname and port or display of the VNC 11999 server, e.g. 12.34.56.78:0 or snoopy.com:1. Note that when 12000 using -repeater, the host:dpy on the cmdline is the repeate 12001 r 12002 server, NOT the VNC server. The repeater will connect you. 12003 12004 Example: vncviewer ... -repeater ID:3333 repeat.host:5900 12005 Example: vncviewer ... -repeater vhost:0 repeat.host:5900 12006 12007 Use, e.g., '-repeater SCIII=ID:3210' if the repeater is a 12008 Single Click III (SSL) repeater (repeater_SSL.exe) and you 12009 are passing the SSL part of the connection through stunnel, 12010 socat, etc. This way the magic UltraVNC string 'testB' 12011 needed to work with the repeater is sent to it. 12012 12013 -rfbversion str Set the advertised RFB version. E.g.: -rfbversion 3.6 12014 For some servers, e.g. UltraVNC this needs to be done. 12015 12016 -ultradsm UltraVNC has symmetric private key encryption DSM plugins: 12017 http://www.uvnc.com/features/encryption.html. It is assumed 12018 you are using a unix program (e.g. our ultravnc_dsm_helper) 12019 to encrypt and decrypt the UltraVNC DSM stream. IN ADDITION 12020 TO THAT supply -ultradsm to tell THIS viewer to modify the 12021 RFB data sent so as to work with the UltraVNC Server. For 12022 some reason, each RFB msg type must be sent twice under DSM 12023 . 12024 12025 -mslogon user Use Windows MS Logon to an UltraVNC server. Supply the 12026 username or "1" to be prompted. The default is to 12027 autodetect the UltraVNC MS Logon server and prompt for 12028 the username and password. 12029 12030 IMPORTANT NOTE: The UltraVNC MS-Logon Diffie-Hellman 12031 exchange is very weak and can be brute forced to recover 12032 your username and password in a few seconds of CPU time. 12033 To be safe, be sure to use an additional encrypted tunnel 12034 (e.g. SSL or SSH) for the entire VNC session. 12035 12036 -chatonly Try to be a client that only does UltraVNC text chat. This 12037 mode is used by x11vnc to present a chat window on the 12038 physical X11 console (i.e. chat with the person at the 12039 display). 12040 12041 -env VAR=VALUE To save writing a shell script to set environment variables 12042 , 12043 specify as many as you need on the command line. For 12044 example, -env SSVNC_MULTIPLE_LISTEN=MAX:5 -env EDITOR=vi 12045 12046 -noipv6 Disable all IPv6 sockets. Same as VNCVIEWER_NO_IPV6=1. 12047 12048 -noipv4 Disable all IPv4 sockets. Same as VNCVIEWER_NO_IPV4=1. 12049 12050 -printres Print out the Ssvnc X resources (appdefaults) and then exit 12051 You can save them to a file and customize them (e.g. the 12052 keybindings and Popup menu) Then point to the file via 12053 XENVIRONMENT or XAPPLRESDIR. 12054 12055 -pipeline Like TurboVNC, request the next framebuffer update as soon 12056 as possible instead of waiting until the end of the current 12057 framebuffer update coming in. Helps 'pipeline' the updates 12058 . 12059 This is currently the default, use -nopipeline to disable. 12060 12061 -appshare Enable features for use with x11vnc's -appshare mode where 12062 instead of sharing the full desktop only the application's 12063 windows are shared. Viewer multilisten mode is used to 12064 create the multiple windows: -multilisten is implied. 12065 See 'x11vnc -appshare -help' more information on the mode. 12066 12067 Features enabled in the viewer under -appshare are: 12068 Minimum extra text in the title, auto -ycrop is disabled, 12069 x11vnc -remote_prefix X11VNC_APPSHARE_CMD: message channel, 12070 x11vnc initial window position hints. See also Escape Keys 12071 below for additional key and mouse bindings. 12072 12073 -escape str This sets the 'Escape Keys' modifier sequence and enables 12074 escape keys mode. When the modifier keys escape sequence 12075 is held down, the next keystroke is interpreted locally 12076 to perform a special action instead of being sent to the 12077 remote VNC server. 12078 12079 Use '-escape default' for the default modifier sequence. 12080 (Unix: Alt_L,Super_L and MacOSX: Control_L,Meta_L) 12081 12082 Here are the 'Escape Keys: Help+Set' instructions from the Popup Menu: 12083 12084 Escape Keys: Enter a comma separated list of modifier keys to be the 12085 'escape sequence'. When these keys are held down, the next keystroke is 12086 interpreted locally to invoke a special action instead of being sent to 12087 the remote VNC server. In other words, a set of 'Hot Keys'. 12088 12089 To enable or disable this, click on 'Escape Keys: Toggle' in the Popup. 12090 12091 Here is the list of hot-key mappings to special actions: 12092 12093 r: refresh desktop b: toggle bell c: toggle full-color 12094 f: file transfer x: x11cursor z: toggle Tight/ZRLE 12095 l: full screen g: graball e: escape keys dialog 12096 s: scale dialog +: scale up (=) -: scale down (_) 12097 t: text chat a: alphablend cursor 12098 V: toggle viewonly Q: quit viewer 1 2 3 4 5 6: UltraVNC scale 1/n 12099 12100 Arrow keys: pan the viewport about 10% for each keypress. 12101 PageUp / PageDown: pan the viewport by a screenful vertically. 12102 Home / End: pan the viewport by a screenful horizontally. 12103 KeyPad Arrow keys: pan the viewport by 1 pixel for each keypress. 12104 Dragging the Mouse with Button1 pressed also pans the viewport. 12105 Clicking Mouse Button3 brings up the Popup Menu. 12106 12107 The above mappings are *always* active in ViewOnly mode, unless you set the 12108 Escape Keys value to 'never'. 12109 12110 If the Escape Keys value below is set to 'default' then a default list of 12111 of modifier keys is used. For Unix it is: Alt_L,Super_L and for MacOSX it 12112 is Control_L,Meta_L. Note: the Super_L key usually has a Windows(TM) Flag 12113 on it. Also note the _L and _R mean the key is on the LEFT or RIGHT side 12114 of the keyboard. 12115 12116 On Unix the default is Alt and Windows keys on Left side of keyboard. 12117 On MacOSX the default is Control and Command keys on Left side of keyboard. 12118 12119 Example: Press and hold the Alt and Windows keys on the LEFT side of the 12120 keyboard and then press 'c' to toggle the full-color state. Or press 't' 12121 to toggle the ultravnc Text Chat window, etc. 12122 12123 To use something besides the default, supply a comma separated list (or a 12124 single one) from: Shift_L Shift_R Control_L Control_R Alt_L Alt_R Meta_L 12125 Meta_R Super_L Super_R Hyper_L Hyper_R or Mode_switch. 12126 12127 12128 New Popup actions: 12129 12130 ViewOnly: ~ -viewonly 12131 Disable Bell: ~ -nobell 12132 Cursor Shape: ~ -nocursorshape 12133 X11 Cursor: ~ -x11cursor 12134 Cursor Alphablend: ~ -alpha 12135 Toggle Tight/Hextile: ~ -encodings hextile... 12136 Toggle Tight/ZRLE: ~ -encodings zrle... 12137 Toggle ZRLE/ZYWRLE: ~ -encodings zywrle... 12138 Quality Level ~ -quality (both Tight and ZYWRLE) 12139 Compress Level ~ -compresslevel 12140 Disable JPEG: ~ -nojpeg (Tight) 12141 Pipeline Updates ~ -pipeline 12142 12143 Full Color as many colors as local screen allows. 12144 Grey scale (16 & 8-bpp) ~ -grey, for low colors 16/8bpp modes only. 12145 16 bit color (BGR565) ~ -16bpp / -bgr565 12146 8 bit color (BGR233) ~ -bgr233 12147 256 colors ~ -bgr233 default # of colors. 12148 64 colors ~ -bgr222 / -use64 12149 8 colors ~ -bgr111 / -use8 12150 Scale Viewer ~ -scale 12151 Escape Keys: Toggle ~ -escape 12152 Escape Keys: Help+Set ~ -escape 12153 Set Y Crop (y-max) ~ -ycrop 12154 Set Scrollbar Width ~ -sbwidth 12155 XGrabServer ~ -graball 12156 12157 UltraVNC Extensions: 12158 12159 Set 1/n Server Scale Ultravnc ext. Scale desktop by 1/n. 12160 Text Chat Ultravnc ext. Do Text Chat. 12161 File Transfer Ultravnc ext. File xfer via Java helper. 12162 Single Window Ultravnc ext. Grab and view a single window. 12163 (select then click on the window you want). 12164 Disable Remote Input Ultravnc ext. Try to prevent input and 12165 viewing of monitor at physical display. 12166 12167 Note: the Ultravnc extensions only apply to servers that support 12168 them. x11vnc/libvncserver supports some of them. 12169 12170 Send Clipboard not Primary ~ -sendclipboard 12171 Send Selection Every time ~ -sendalways 12172 12173 Nearly all of these can be changed dynamically in the Popup menu 12174 (press F8 for it): 12175 12176 [viewer_menu.gif] [unixviewer.jpg] 12177 12178 _________________________________________________________________ 12179 12180 Windows: 12181 12182 For Windows, SSL Viewer support is provided by a GUI Windows/ssvnc.exe 12183 that prompts for the VNC display and then starts up STUNNEL followed 12184 by the Stock TightVNC Windows Viewer. Both are bundled in the package 12185 for your convenience. The GUI has other useful features. When the 12186 connection is finished, you will be asked if you want to terminate the 12187 STUNNEL program. For SSH connections from Windows the GUI will use 12188 PLINK instead of STUNNEL. 12189 12190 Unix and Mac OS X: 12191 12192 Run the GUI (ssvnc, see above) and let me know how it goes. 12193 _________________________________________________________________ 12194 12195 Hopefully this tool will make it convenient for people to help test 12196 and use the built-in SSL support in x11vnc. Extra testing of this 12197 feature is much appreciated!! Thanks. 12198 12199 Please Help Test the newly added features: 12200 * Automatic Service tunnelling via SSH for CUPS and SMB Printing 12201 * ESD/ARTSD Audio 12202 * SMB (Windows/Samba) filesystem mounting 12203 12204 These allow you to print from the remote (VNC Server) machine to local 12205 printers, listen to sounds (with some limitations) from the remote VNC 12206 Server machine, and to mount your local Windows or Samba shares on the 12207 remote VNC Server machine. Basically these new features try to 12208 automate the tricks described here: 12209 http://www.karlrunge.com/x11vnc/faq.html#faq-smb-shares 12210 http://www.karlrunge.com/x11vnc/faq.html#faq-cups 12211 http://www.karlrunge.com/x11vnc/faq.html#faq-sound 12212 _________________________________________________________________ 12213 12214 Downloading: Downloads for this project are hosted at Sourceforge.net. 12215 12216 Choose the archive file bundle that best suits you (e.g. no source 12217 code, windows only, unix only, zip, tar etc). 12218 12219 A quick guide: 12220 12221 On some flavor of Unix, e.g. Linux or Solaris? Use 12222 "ssvnc_unix_only" (or "ssvnc_no_windows" to recompile). 12223 On Mac OS X? Use "ssvnc_no_windows". 12224 On Windows? Use "ssvnc_windows_only". 12225 ssvnc_windows_only-1.0.28.zip Windows Binaries Only. No source included 12226 (6.2MB) 12227 ssvnc_no_windows-1.0.28.tar.gz Unix and Mac OS X Only. No Windows binarie 12228 s. Source included. (10.1MB) 12229 ssvnc_unix_only-1.0.28.tar.gz Unix Binaries Only. No source included 12230 . (7.2MB) 12231 ssvnc_unix_minimal-1.0.28.tar.gz Unix Minimal. You must supply your own vn 12232 cviewer and stunnel. (0.2MB) 12233 12234 ssvnc-1.0.28.tar.gz All Unix, Mac OS X, and Windows binaries a 12235 nd source TGZ. (16.1MB) 12236 ssvnc-1.0.28.zip All Unix, Mac OS X, and Windows binaries a 12237 nd source ZIP. (16.4MB) 12238 ssvnc_all-1.0.28.zip All Unix, Mac OS X, and Windows binaries a 12239 nd source AND full archives in the zip dir. (19.2MB) 12240 12241 12242 Here is a conventional source tarball: 12243 ssvnc-1.0.28.src.tar.gz Conventional Source for SSVNC GUI and Unix 12244 VNCviewer (0.5MB) 12245 12246 it will be of use to those who do not want the SSVNC 12247 "one-size-fits-all" bundles. For example, package/distro maintainers 12248 will find this more familiar and useful to them (i.e. they run: "make 12249 config; make all; make install"). Note that it does not include the 12250 stunnel source, and so has a dependency that the system stunnel is 12251 installed. 12252 12253 Read the README.src file for more information on using the 12254 conventional source tarball. 12255 12256 12257 Note: even with the Unix bundles, e.g. "ssvnc_no_windows" or 12258 "ssvnc_all", you may need to run the "./build.unix" script in the top 12259 directory to recompile for your operating system. 12260 12261 Here are the corresponding 1.0.29 development bundles (Please help 12262 test them): 12263 12264 ssvnc_windows_only-1.0.29.zip 12265 ssvnc_no_windows-1.0.29.tar.gz 12266 ssvnc_unix_only-1.0.29.tar.gz 12267 ssvnc_unix_minimal-1.0.29.tar.gz 12268 12269 ssvnc-1.0.29.tar.gz 12270 ssvnc-1.0.29.zip 12271 ssvnc_all-1.0.29.zip 12272 12273 ssvnc-1.0.29.src.tar.gz Conventional Source for SSVNC GUI and Unix 12274 VNCviewer (0.5MB) 12275 12276 12277 For any Unix system, a self-extracting and running file for the 12278 "ssvnc_unix_minimal" package is here: ssvnc. Save it as filename 12279 "ssvnc", type "chmod 755 ./ssvnc", and then launch the GUI via typing 12280 "./ssvnc". Note that this "ssvnc_unix_minimal" mode requires you 12281 install the "stunnel" and "vncviewer" programs externally (for 12282 example, install your distros' versions, e.g. on debian: "apt-get 12283 install stunnel4 xtightvncviewer".) It will work, but many of the 12284 SSVNC features will be missing. 12285 12286 Previous releases: 12287 Release 1.0.18 at Sourceforge.net 12288 Release 1.0.19 at Sourceforge.net 12289 Release 1.0.20 at Sourceforge.net 12290 Release 1.0.21 at Sourceforge.net 12291 Release 1.0.22 at Sourceforge.net 12292 Release 1.0.23 at Sourceforge.net 12293 Release 1.0.24 at Sourceforge.net 12294 Release 1.0.25 at Sourceforge.net 12295 Release 1.0.26 at Sourceforge.net 12296 Release 1.0.27 at Sourceforge.net 12297 Release 1.0.28 at Sourceforge.net 12298 12299 12300 Please help test the UltraVNC File Transfer support in the native Unix 12301 VNC viewer! Let us know how it went. 12302 12303 Current Unix binaries in the archives: 12304 Linux.i686 12305 Linux.x86_64 12306 Linux.ppc64 X (removed) 12307 Linux.alpha X (removed) 12308 SunOS.sun4u 12309 SunOS.sun4m 12310 SunOS.i86pc 12311 Darwin.Power.Macintosh 12312 Darwin.i386 12313 HP-UX.9000 X (removed) 12314 FreeBSD.i386 X (removed) 12315 NetBSD.i386 X (removed) 12316 OpenBSD.i386 X (removed) 12317 12318 (some of these are out of date, marked with 'X' above, because I no 12319 longer have access to machines running those OS's. Use the 12320 "build.unix" script to recompile on your system). 12321 12322 Note: some of the above binaries depend on libssl.so.0.9.7, whereas 12323 some recent distros only provide libssl.so.0.9.8 by default (for 12324 compatibility reasons they should install both by default but not all 12325 do). So you may need to instruct your distro to install the 0.9.7 12326 library (it is fine to have both runtimes installed simultaneously 12327 since the libraries have different names). Update: I now try to 12328 statically link libssl.a for all of the binaries in the archive. 12329 12330 You can also run the included build.unix script to try to 12331 automatically build the binaries if your OS is not in the above list 12332 or the included binary does not run properly on your system. Let me 12333 know how that goes. 12334 _________________________________________________________________ 12335 12336 IMPORTANT: there may be restrictions for you to download, use, or 12337 redistribute the above because of cryptographic software they contain 12338 or for other reasons. Please check out your situation and information 12339 at the following and related sites: 12340 http://stunnel.mirt.net 12341 http://www.stunnel.org 12342 http://www.openssl.org 12343 http://www.chiark.greenend.org.uk/~sgtatham/putty/ 12344 http://www.tightvnc.com 12345 http://www.realvnc.com 12346 http://sourceforge.net/projects/cotvnc/ 12347 _________________________________________________________________ 12348 12349 README: Here is the toplevel README from the bundle. 12350 12351 ======================================================================= 12352 http://www.karlrunge.com/x11vnc/x11vnc_opts.html: 12353 12354 12355 _________________________________________________________________ 12356 12357 x11vnc: a VNC server for real X displays 12358 12359 Here are all of x11vnc command line options: 12360 % x11vnc -opts (see below for -help long descriptions) 12361 12362 x11vnc: allow VNC connections to real X11 displays. 0.9.13 lastmod: 2010-12-27 12363 12364 x11vnc options: 12365 -display disp -auth file -N 12366 -autoport n -rfbport str -6 12367 -no6 -noipv6 -noipv4 12368 -reopen -reflect host:N -id windowid 12369 -sid windowid -appshare -clip WxH+X+Y 12370 -flashcmap -shiftcmap n -notruecolor 12371 -advertise_truecolor -visual n -overlay 12372 -overlay_nocursor -8to24 [opts] -24to32 12373 -scale fraction -geometry WxH -scale_cursor frac 12374 -viewonly -shared -once 12375 -forever -loop -timeout n 12376 -sleepin n -inetd -tightfilexfer 12377 -ultrafilexfer -http -http_ssl 12378 -avahi -mdns -zeroconf 12379 -connect string -connect_or_exit str -proxy string 12380 -vncconnect -novncconnect -allow host1[,host2..] 12381 -localhost -unixsock str -listen6 str 12382 -nolookup -input string -grabkbd 12383 -grabptr -ungrabboth -grabalways 12384 -viewpasswd string -passwdfile filename -showrfbauth filename 12385 -unixpw [list] -unixpw_nis [list] -unixpw_cmd cmd 12386 -find -finddpy -listdpy 12387 -findauth [disp] -create -xdummy 12388 -xvnc -xvnc_redirect -xdummy_xvfb 12389 -create_xsrv str -svc -svc_xdummy 12390 -svc_xvnc -svc_xdummy_xvfb -xdmsvc 12391 -sshxdmsvc -unixpw_system_greeter -redirect port 12392 -display WAIT:... -vencrypt mode -anontls mode 12393 -sslonly -dhparams file -nossl 12394 -ssl [pem] -ssltimeout n -sslnofail 12395 -ssldir dir -sslverify path -sslCRL path 12396 -sslGenCA [dir] -sslGenCert type name -sslEncKey pem 12397 -sslCertInfo pem -sslDelCert pem -sslScripts 12398 -stunnel [pem] -stunnel3 [pem] -enc cipher:keyfile 12399 -https [port] -httpsredir [port] -http_oneport 12400 -ssh user@host:disp -usepw -storepasswd pass file 12401 -nopw -accept string -afteraccept string 12402 -gone string -users list -noshm 12403 -flipbyteorder -onetile -solid [color] 12404 -blackout string -xinerama -noxinerama 12405 -xtrap -xrandr [mode] -rotate string 12406 -padgeom WxH -o logfile -flag file 12407 -rmflag file -rc filename -norc 12408 -env VAR=VALUE -prog /path/to/x11vnc -h, -help 12409 -?, -opts -V, -version -license 12410 -dbg -q, -quiet -v, -verbose 12411 -bg -modtweak -nomodtweak 12412 -xkb -noxkb -capslock 12413 -skip_lockkeys -noskip_lockkeys -skip_keycodes string 12414 -sloppy_keys -skip_dups -noskip_dups 12415 -add_keysyms -noadd_keysyms -clear_mods 12416 -clear_keys -clear_all -remap string 12417 -norepeat -repeat -nofb 12418 -nobell -nosel -noprimary 12419 -nosetprimary -noclipboard -nosetclipboard 12420 -seldir string -cursor [mode] -nocursor 12421 -cursor_drag -arrow n -noxfixes 12422 -alphacut n -alphafrac fraction -alpharemove 12423 -noalphablend -nocursorshape -cursorpos 12424 -nocursorpos -xwarppointer -noxwarppointer 12425 -always_inject -buttonmap string -nodragging 12426 -ncache n -ncache_cr -ncache_no_moveraise 12427 -ncache_no_dtchange -ncache_no_rootpixmap -ncache_keep_anims 12428 -ncache_old_wm -ncache_pad n -debug_ncache 12429 -wireframe [str] -nowireframe -nowireframelocal 12430 -wirecopyrect mode -nowirecopyrect -debug_wireframe 12431 -scrollcopyrect mode -noscrollcopyrect -scr_area n 12432 -scr_skip list -scr_inc list -scr_keys list 12433 -scr_term list -scr_keyrepeat lo-hi -scr_parms string 12434 -fixscreen string -debug_scroll -noxrecord 12435 -grab_buster -nograb_buster -debug_grabs 12436 -debug_sel -pointer_mode n -input_skip n 12437 -allinput -input_eagerly -speeds rd,bw,lat 12438 -wmdt string -debug_pointer -debug_keyboard 12439 -defer time -wait time -extra_fbur n 12440 -wait_ui factor -setdefer n -nowait_bog 12441 -slow_fb time -xrefresh time -nap 12442 -nonap -sb time -readtimeout n 12443 -ping n -nofbpm -fbpm 12444 -nodpms -dpms -forcedpms 12445 -clientdpms -noserverdpms -noultraext 12446 -chatwindow -noxdamage -xd_area A 12447 -xd_mem f -sigpipe string -threads 12448 -nothreads -fs f -gaps n 12449 -grow n -fuzz n -debug_tiles 12450 -snapfb -rawfb string -freqtab file 12451 -pipeinput cmd -macnodim -macnosleep 12452 -macnosaver -macnowait -macwheel n 12453 -macnoswap -macnoresize -maciconanim n 12454 -macmenu -macuskbd -macnoopengl 12455 -macnorawfb -gui [gui-opts] -remote command 12456 -query variable -QD variable -sync 12457 -query_retries str -remote_prefix str -noremote 12458 -yesremote -unsafe -safer 12459 -privremote -nocmds -allowedcmds list 12460 -deny_all 12461 12462 LibVNCServer options: 12463 -rfbport port TCP port for RFB protocol 12464 -rfbwait time max time in ms to wait for RFB client 12465 -rfbauth passwd-file use authentication on RFB protocol 12466 (use 'storepasswd' to create a password file) 12467 -rfbversion 3.x Set the version of the RFB we choose to advertise 12468 -permitfiletransfer permit file transfer support 12469 -passwd plain-password use authentication 12470 (use plain-password as password, USE AT YOUR RISK) 12471 -deferupdate time time in ms to defer updates (default 40) 12472 -deferptrupdate time time in ms to defer pointer updates (default none) 12473 -desktop name VNC desktop name (default "LibVNCServer") 12474 -alwaysshared always treat new clients as shared 12475 -nevershared never treat new clients as shared 12476 -dontdisconnect don't disconnect existing clients when a new non-shared 12477 connection comes in (refuse new connection instead) 12478 -httpdir dir-path enable http server using dir-path home 12479 -httpport portnum use portnum for http connection 12480 -enablehttpproxy enable http proxy support 12481 -progressive height enable progressive updating for slow links 12482 -listen ipaddr listen for connections only on network interface with 12483 addr ipaddr. '-listen localhost' and hostname work too. 12484 12485 libvncserver-tight-extension options: 12486 -disablefiletransfer disable file transfer 12487 -ftproot string set ftp root 12488 12489 12490 12491 12492 % x11vnc -help 12493 12494 x11vnc: allow VNC connections to real X11 displays. 0.9.13 lastmod: 2010-12-27 12495 12496 (type "x11vnc -opts" to just list the options.) 12497 12498 Typical usage is: 12499 12500 Run this command in a shell on the remote machine "far-host" 12501 with X session you wish to view: 12502 12503 x11vnc -display :0 12504 12505 Then run this in another window on the machine you are sitting at: 12506 12507 vncviewer far-host:0 12508 12509 Once x11vnc establishes connections with the X11 server and starts listening 12510 as a VNC server it will print out a string: PORT=XXXX where XXXX is typically 12511 5900 (the default VNC server port). One would next run something like 12512 this on the local machine: "vncviewer hostname:N" where "hostname" is 12513 the name of the machine running x11vnc and N is XXXX - 5900, i.e. usually 12514 "vncviewer hostname:0". 12515 12516 By default x11vnc will not allow the screen to be shared and it will exit 12517 as soon as the client disconnects. See -shared and -forever below to override 12518 these protections. See the FAQ for details how to tunnel the VNC connection 12519 through an encrypted channel such as ssh(1). In brief: 12520 12521 ssh -t -L 5900:localhost:5900 far-host 'x11vnc -localhost -display :0' 12522 12523 vncviewer -encodings 'copyrect tight zrle hextile' localhost:0 12524 12525 Also, use of a VNC password (-rfbauth or -passwdfile) is strongly recommended. 12526 12527 For additional info see: http://www.karlrunge.com/x11vnc/ 12528 and http://www.karlrunge.com/x11vnc/faq.html 12529 12530 12531 Config file support: if the file $HOME/.x11vncrc exists then each line in 12532 it is treated as a single command line option. Disable with -norc. For 12533 each option name, the leading character "-" is not required. E.g. a line 12534 that is either "forever" or "-forever" may be used and are equivalent. 12535 Likewise "wait 100" or "-wait 100" are acceptable and equivalent lines. 12536 The "#" character comments out to the end of the line in the usual way 12537 (backslash it for a literal). Leading and trailing whitespace is trimmed off. 12538 Lines may be continued with a "\" as the last character of a line (it 12539 becomes a space character). 12540 12541 Options: 12542 12543 -display disp X11 server display to connect to, usually :0. The X 12544 server process must be running on same machine and 12545 support MIT-SHM. Equivalent to setting the DISPLAY 12546 environment variable to "disp". 12547 12548 See the description below of the "-display WAIT:..." 12549 extensions, where alias "-find" will find the user's 12550 display automatically, and "-create" will create a 12551 Xvfb session if no session is found. 12552 12553 -auth file Set the X authority file to be "file", equivalent to 12554 setting the XAUTHORITY environment variable to "file" 12555 before startup. Same as -xauth file. See Xsecurity(7), 12556 xauth(1) man pages for more info. 12557 12558 Use '-auth guess' to have x11vnc use its -findauth 12559 mechanism (described below) to try to guess the 12560 XAUTHORITY filename and use it. 12561 12562 XDM/GDM/KDM: if you are running x11vnc as root and want 12563 to find the XAUTHORITY before anyone has logged into an 12564 X session yet, use: x11vnc -env FD_XDM=1 -auth guess ... 12565 (This will also find the XAUTHORITY if a user is already 12566 logged into the X session.) When running as root, 12567 FD_XDM=1 will be tried if the initial -auth guess fails. 12568 12569 -N If the X display is :N, try to set the VNC display to 12570 also be :N This just sets the -rfbport option to 5900+N 12571 The program will exit immediately if that port is not 12572 available. The -N option only works with normal -display 12573 usage, e.g. :0 or :8, -N is ignored in the -display 12574 WAIT:..., -create, -find, -svc, -redirect, etc modes. 12575 12576 -autoport n Automatically probe for a free VNC port starting at n. 12577 The default is to start probing at 5900. Use this to 12578 stay away from other VNC servers near 5900. 12579 12580 -rfbport str The VNC port to listen on (a LibVNCServer option), e.g. 12581 5900, 5901, etc. If specified as "-rfbport PROMPT" 12582 then the x11vnc -gui is used to prompt the user to 12583 enter the port number. 12584 12585 -6 IPv6 listening support. In addition to IPv4, the 12586 IPv6 address is listened on for incoming connections. 12587 The same port number as IPv4 is used. 12588 12589 NOTE: This x11vnc binary was compiled to have the 12590 "-6" IPv6 listening mode ENABLED by default (CPPFLAGS 12591 -DX11VNC_LISTEN6=1). So to disable IPv6 listening mode 12592 you MUST supply the "-no6" option (see below.) 12593 12594 The "-6" mode works for both normal connections and 12595 -ssl encrypted ones. Nearly everything is supported 12596 for the IPv6 case, but there are a few exceptions. 12597 See -stunnel for its IPv6 support. 12598 12599 Currently, for absolutely everything to work correctly 12600 the machine may need to have some IPv4 support, at the 12601 least for the loopback interface. However, for nearly 12602 all usage modes no IPv4 support is required. See -nopiv4 12603 . 12604 12605 If you have trouble compiling or running in IPv6 mode, 12606 set -DX11VNC_IPV6=0 in CPPFLAGS when configuring to 12607 disable IPv6 support. 12608 12609 -no6 Disable IPv6 listening support (only useful if the 12610 "-6" mode is compiled in to be the default; see the 12611 X11VNC_LISTEN6 description above under "-6".) 12612 12613 -noipv6 Do not try to use IPv6 for any listening or connecting 12614 sockets. This includes both the listening service 12615 port(s) and outgoing connections from -connect, 12616 -connect_or_exit, or -proxy. Use this if you are having 12617 problems due to IPv6. 12618 12619 -noipv4 Do not try to use IPv4 for any listening or connecting 12620 sockets. This is mainly for exploring the behavior of 12621 x11vnc on an IPv6-only system, but may have other uses. 12622 12623 -reopen If the X server connection is disconnected, try to 12624 reopen the X display (up to one time.) This is of use 12625 for display managers like GDM (KillInitClients option) 12626 that kill x11vnc just after the user logs into the 12627 X session. Note: the reopened state may be unstable. 12628 Set X11VNC_REOPEN_DISPLAY=n to reopen n times and 12629 set X11VNC_REOPEN_SLEEP_MAX to the number of seconds, 12630 default 10, to keep trying to reopen the display (once 12631 per second.) 12632 12633 Update: as of 0.9.9, x11vnc tries to automatically avoid 12634 being killed by the display manager by delaying creating 12635 windows or using XFIXES. So you shouldn't need to use 12636 KillInitClients=false as long as you log in quickly 12637 enough (within 45 seconds of connecting.) You can 12638 disable this by setting X11VNC_AVOID_WINDOWS=never. 12639 You can also set it to the number of seconds to delay. 12640 12641 -reflect host:N Instead of connecting to and polling an X display, 12642 connect to the remote VNC server host:N and be a 12643 reflector/repeater for it. This is useful for trying 12644 to manage the case of many simultaneous VNC viewers 12645 (e.g. classroom broadcasting) where, e.g. you put 12646 a repeater on each network switch, etc, to improve 12647 performance by distributing the load and network 12648 traffic. Implies -shared (use -noshared as a later 12649 option to disable). See the discussion below under 12650 -rawfb vnc:host:N for more details. 12651 12652 -id windowid Show the X window corresponding to "windowid" not 12653 the entire display. New windows like popup menus, 12654 transient toplevels, etc, may not be seen or may be 12655 clipped. Disabling SaveUnders or BackingStore in the 12656 X server may help show them. x11vnc may crash if the 12657 window is initially partially obscured, changes size, 12658 is iconified, etc. Some steps are taken to avoid this 12659 and the -xrandr mechanism is used to track resizes. Use 12660 xwininfo(1) to get the window id, or use "-id pick" 12661 to have x11vnc run xwininfo(1) for you and extract 12662 the id. The -id option is useful for exporting very 12663 simple applications (e.g. the current view on a webcam). 12664 -sid windowid As -id, but instead of using the window directly it 12665 shifts a root view to it: this shows SaveUnders menus, 12666 etc, although they will be clipped if they extend beyond 12667 the window. 12668 12669 -appshare Simple application sharing based on the -id/-sid 12670 mechanism. Every new toplevel window that the 12671 application creates induces a new viewer window via 12672 a reverse connection. The -id/-sid and -connect 12673 options are required. Run 'x11vnc -appshare -help' 12674 for more info. 12675 12676 -clip WxH+X+Y Only show the sub-region of the full display that 12677 corresponds to the rectangle geometry with size WxH and 12678 offset +X+Y. The VNC display has size WxH (i.e. smaller 12679 than the full display). This also works for -id/-sid 12680 mode where the offset is relative to the upper left 12681 corner of the selected window. An example use of this 12682 option would be to split a large (e.g. Xinerama) display 12683 into two parts to be accessed via separate viewers by 12684 running a separate x11vnc on each part. 12685 12686 Use '-clip xinerama0' to clip to the first xinerama 12687 sub-screen (if xinerama is active). xinerama1 for the 12688 2nd sub-screen, etc. This way you don't need to figure 12689 out the WxH+X+Y of the desired xinerama sub-screen. 12690 screens are sorted in increasing distance from the 12691 (0,0) origin (I.e. not the Xserver's order). 12692 12693 -flashcmap In 8bpp indexed color, let the installed colormap flash 12694 as the pointer moves from window to window (slow). 12695 Also try the -8to24 option to avoid flash altogether. 12696 -shiftcmap n Rare problem, but some 8bpp displays use less than 256 12697 colorcells (e.g. 16-color grayscale, perhaps the other 12698 bits are used for double buffering) *and* also need to 12699 shift the pixels values away from 0, .., ncells. "n" 12700 indicates the shift to be applied to the pixel values. 12701 To see the pixel values set DEBUG_CMAP=1 to print out 12702 a colormap histogram. Example: -shiftcmap 240 12703 -notruecolor For 8bpp displays, force indexed color (i.e. a colormap) 12704 even if it looks like 8bpp TrueColor (rare problem). 12705 -advertise_truecolor If the X11 display is indexed color, lie to clients 12706 when they first connect by telling them it is truecolor. 12707 To workaround RealVNC: inPF has colourMap but not 8bpp 12708 Use '-advertise_truecolor reset' to reset client fb too. 12709 12710 -visual n This option probably does not do what you think. 12711 It simply *forces* the visual used for the framebuffer; 12712 this may be a bad thing... (e.g. messes up colors or 12713 cause a crash). It is useful for testing and for some 12714 workarounds. n may be a decimal number, or 0x hex. 12715 Run xdpyinfo(1) for the values. One may also use 12716 "TrueColor", etc. see <X11/X.h> for a list. If the 12717 string ends in ":m" then for better or for worse 12718 the visual depth is forced to be m. You may want to 12719 use -noshm when using this option (so XGetImage may 12720 automatically translate the pixel data). 12721 12722 -overlay Handle multiple depth visuals on one screen, e.g. 8+24 12723 and 24+8 overlay visuals (the 32 bits per pixel are 12724 packed with 8 for PseudoColor and 24 for TrueColor). 12725 12726 Currently -overlay only works on Solaris via 12727 XReadScreen(3X11) and IRIX using XReadDisplay(3). 12728 On Solaris there is a problem with image "bleeding" 12729 around transient popup menus (but not for the menu 12730 itself): a workaround is to disable SaveUnders 12731 by passing the "-su" argument to Xsun (in 12732 /etc/dt/config/Xservers). 12733 12734 Use -overlay as a workaround for situations like these: 12735 Some legacy applications require the default visual to 12736 be 8bpp (8+24), or they will use 8bpp PseudoColor even 12737 when the default visual is depth 24 TrueColor (24+8). 12738 In these cases colors in some windows will be incorrect 12739 in x11vnc unless -overlay is used. Another use of 12740 -overlay is to enable showing the exact mouse cursor 12741 shape (details below). 12742 12743 Under -overlay, performance will be somewhat slower 12744 due to the extra image transformations required. 12745 For optimal performance do not use -overlay, but rather 12746 configure the X server so that the default visual is 12747 depth 24 TrueColor and try to have all apps use that 12748 visual (e.g. some apps have -use24 or -visual options). 12749 -overlay_nocursor Sets -overlay, but does not try to draw the exact mouse 12750 cursor shape using the overlay mechanism. 12751 12752 -8to24 [opts] Try this option if -overlay is not supported on your 12753 OS, and you have a legacy 8bpp app that you want to 12754 view on a multi-depth display with default depth 24 12755 (and is 32 bpp) OR have a default depth 8 display with 12756 depth 24 overlay windows for some apps. This option 12757 may not work on all X servers and hardware (tested 12758 on XFree86/Xorg mga driver and Xsun). The "opts" 12759 string is not required and is described below. 12760 12761 This mode enables a hack where x11vnc monitors windows 12762 within 3 levels from the root window. If it finds 12763 any that are 8bpp it extracts the indexed color 12764 pixel values using XGetImage() and then applies a 12765 transformation using the colormap(s) to create TrueColor 12766 RGB values that it in turn inserts into bits 1-24 of 12767 the framebuffer. This creates a depth 24 "view" 12768 of the display that is then exported via VNC. 12769 12770 Conversely, for default depth 8 displays, the depth 12771 24 regions are read by XGetImage() and everything is 12772 transformed and inserted into a depth 24 TrueColor 12773 framebuffer. 12774 12775 Note that even if there are *no* depth 24 visuals or 12776 windows (i.e. pure 8bpp), this mode is potentially 12777 an improvement over -flashcmap because it avoids the 12778 flashing and shows each window in the correct color. 12779 12780 This method works OK, but may still have bugs and it 12781 does hog resources. If there are multiple 8bpp windows 12782 using different colormaps, one may have to iconify all 12783 but one for the colors to be correct. 12784 12785 There may be painting errors for clipping and switching 12786 between windows of depths 8 and 24. Heuristics are 12787 applied to try to minimize the painting errors. One can 12788 also press 3 Alt_L's in a row to refresh the screen 12789 if the error does not repair itself. Also the option 12790 -fixscreen 8=3.0 or -fixscreen V=3.0 may be used to 12791 periodically refresh the screen at the cost of bandwidth 12792 (every 3 sec for this example). 12793 12794 The [opts] string can contain the following settings. 12795 Multiple settings are separated by commas. 12796 12797 For for some X servers with default depth 24 a 12798 speedup may be achieved via the option "nogetimage". 12799 This enables a scheme were XGetImage() is not used 12800 to retrieve the 8bpp data. Instead, it assumes that 12801 the 8bpp data is in bits 25-32 of the 32bit X pixels. 12802 There is no requirement that the X server should put 12803 the data there for our poll requests, but some do and 12804 so the extra steps to retrieve it can be skipped. 12805 Tested with mga driver with XFree86/Xorg. For the 12806 default depth 8 case this option is ignored. 12807 12808 To adjust how often XGetImage() is used to poll the 12809 non-default visual regions for changes, use the option 12810 "poll=t" where "t" is a floating point time. 12811 (default: 0.05) 12812 12813 Setting the option "level2" will limit the search 12814 for non-default visual windows to two levels from the 12815 root window. Do this on slow machines where you know 12816 the window manager only imposes one extra window between 12817 the app window and the root window. 12818 12819 Also for very slow machines use "cachewin=t" 12820 where t is a floating point amount of time to cache 12821 XGetWindowAttributes results. E.g. cachewin=5.0. 12822 This may lead to the windows being unnoticed for this 12823 amount of time when deiconifying, painting errors, etc. 12824 12825 While testing on a very old SS20 these options gave 12826 tolerable response: -8to24 poll=0.2,cachewin=5.0. For 12827 this machine -overlay is supported and gives better 12828 response. 12829 12830 Debugging for this mode can be enabled by setting 12831 "dbg=1", "dbg=2", or "dbg=3". 12832 12833 -24to32 Very rare problem: if the framebuffer (X display 12834 or -rawfb) is 24bpp instead of the usual 32bpp, then 12835 dynamically transform the pixels to 32bpp. This will be 12836 slower, but can be used to work around problems where 12837 VNC viewers cannot handle 24bpp (e.g. "main: setPF: 12838 not 8, 16 or 32 bpp?"). See the FAQ for more info. 12839 12840 In the case of -rawfb mode, the pixels are directly 12841 modified by inserting a 0 byte to pad them out to 32bpp. 12842 For X displays, a kludge is done that is equivalent to 12843 "-noshm -visual TrueColor:32". (If better performance 12844 is needed for the latter, feel free to ask). 12845 12846 -scale fraction Scale the framebuffer by factor "fraction". Values 12847 less than 1 shrink the fb, larger ones expand it. Note: 12848 the image may not be sharp and response may be slower. 12849 If "fraction" contains a decimal point "." it 12850 is taken as a floating point number, alternatively 12851 the notation "m/n" may be used to denote fractions 12852 exactly, e.g. -scale 2/3 12853 12854 To scale asymmetrically in the horizontal and vertical 12855 directions, specify a WxH geometry to stretch to: 12856 e.g. '-scale 1024x768', or also '-scale 0.9x0.75' 12857 12858 Scaling Options: can be added after "fraction" via 12859 ":", to supply multiple ":" options use commas. 12860 If you just want a quick, rough scaling without 12861 blending, append ":nb" to "fraction" (e.g. -scale 12862 1/3:nb). No blending is the default for 8bpp indexed 12863 color, to force blending for this case use ":fb". 12864 12865 To disable -scrollcopyrect and -wirecopyrect under 12866 -scale use ":nocr". If you need to to enable them use 12867 ":cr" or specify them explicitly on the command line. 12868 If a slow link is detected, ":nocr" may be applied 12869 automatically. Default: :cr 12870 12871 More esoteric options: for compatibility with vncviewers 12872 the scaled width is adjusted to be a multiple of 4: 12873 to disable this use ":n4". ":in" use interpolation 12874 scheme even when shrinking, ":pad" pad scaled width 12875 and height to be multiples of scaling denominator 12876 (e.g. 3 for 2/3). 12877 12878 -geometry WxH Same as -scale WxH 12879 12880 -scale_cursor frac By default if -scale is supplied the cursor shape is 12881 scaled by the same factor. Depending on your usage, 12882 you may want to scale the cursor independently of the 12883 screen or not at all. If you specify -scale_cursor 12884 the cursor will be scaled by that factor. When using 12885 -scale mode to keep the cursor at its "natural" size 12886 use "-scale_cursor 1". Most of the ":" scaling 12887 options apply here as well. 12888 12889 -viewonly All VNC clients can only watch (default off). 12890 -shared VNC display is shared, i.e. more than one viewer can 12891 connect at the same time (default off). 12892 -once Exit after the first successfully connected viewer 12893 disconnects, opposite of -forever. This is the Default. 12894 -forever Keep listening for more connections rather than exiting 12895 as soon as the first client(s) disconnect. Same as -many 12896 12897 To get the standard non-shared VNC behavior where when 12898 a new VNC client connects the existing VNC client is 12899 dropped use: -nevershared -forever This method can 12900 also be used to guard against hung TCP connections that 12901 do not go away. 12902 12903 -loop Create an outer loop restarting the x11vnc process 12904 whenever it terminates. -bg and -inetd are ignored 12905 in this mode (however see -loopbg below). 12906 12907 Useful for continuing even if the X server terminates 12908 and restarts (at that moment the process will need 12909 permission to reconnect to the new X server of course). 12910 12911 Use, e.g., -loop100 to sleep 100 millisecs between 12912 restarts, etc. Default is 2000ms (i.e. 2 secs) Use, 12913 e.g. -loop300,5 to sleep 300 ms and only loop 5 times. 12914 12915 If -loopbg (plus any numbers) is specified instead, 12916 the "-bg" option is implied and the mode approximates 12917 inetd(8) usage to some degree. In this case when 12918 it goes into the background any listening sockets 12919 (i.e. ports 5900, 5800) are closed, so the next one 12920 in the loop can use them. This mode will only be of 12921 use if a VNC client (the only client for that process) 12922 is already connected before the process goes into the 12923 background, for example, usage of -display WAIT:.., 12924 -svc, and -connect can make use of this "poor man's" 12925 inetd mode. The default wait time is 500ms in this 12926 mode. This usage could use useful: -svc -bg -loopbg 12927 12928 -timeout n Exit unless a client connects within the first n seconds 12929 after startup. 12930 12931 If there have been no connection attempts after n 12932 seconds x11vnc exits immediately. If a client is 12933 trying to connect but has not progressed to the normal 12934 operating state, x11vnc gives it a few more seconds 12935 to finish and exits if it does not make it to the 12936 normal state. 12937 12938 For reverse connections via -connect or -connect_or_exit 12939 a timeout of n seconds will be set for all reverse 12940 connects. If the connect timeout alarm goes off, 12941 x11vnc will exit immediately. 12942 12943 -sleepin n At startup sleep n seconds before proceeding (e.g. to 12944 allow redirs and listening clients to start up) 12945 12946 If a range is given: '-sleepin min-max', a random value 12947 between min and max is slept. E.g. '-sleepin 0-20' and 12948 '-sleepin 10-30'. Floats are allowed too. 12949 12950 -inetd Launched by inetd(8): stdio instead of listening socket. 12951 Note: if you are not redirecting stderr to a log file 12952 (via shell 2> or -o option) you MUST also specify the -q 12953 option, otherwise the stderr goes to the viewer which 12954 will cause it to abort. Specifying both -inetd and -q 12955 and no -o will automatically close the stderr. 12956 12957 -tightfilexfer Enable the TightVNC file transfer extension. Note that 12958 that when the -viewonly option is supplied all file 12959 transfers are disabled. Also clients that log in 12960 viewonly cannot transfer files. However, if the remote 12961 control mechanism is used to change the global or 12962 per-client viewonly state the filetransfer permissions 12963 will NOT change. 12964 12965 IMPORTANT: please understand if -tightfilexfer is 12966 specified and you run x11vnc as root for, say, inetd 12967 or display manager (gdm, kdm, ...) access and you do 12968 not have it switch users via the -users option, then 12969 VNC Viewers that connect are able to do filetransfer 12970 reads and writes as *root*. 12971 12972 Also, tightfilexfer is disabled in -unixpw mode. 12973 12974 -ultrafilexfer Note: to enable UltraVNC filetransfer and to get it to 12975 work you probably need to supply these LibVNCServer 12976 options: "-rfbversion 3.6 -permitfiletransfer" 12977 "-ultrafilexfer" is an alias for this combination. 12978 12979 IMPORTANT: please understand if -ultrafilexfer is 12980 specified and you run x11vnc as root for, say, inetd 12981 or display manager (gdm, kdm, ...) access and you do 12982 not have it switch users via the -users option, then 12983 VNC Viewers that connect are able to do filetransfer 12984 reads and writes as *root*. 12985 12986 Note that sadly you cannot do both -tightfilexfer and 12987 -ultrafilexfer at the same time because the latter 12988 requires setting the version to 3.6 and tightvnc will 12989 not do filetransfer when it sees that version number. 12990 12991 -http Instead of using -httpdir (see below) to specify 12992 where the Java vncviewer applet is, have x11vnc try 12993 to *guess* where the directory is by looking relative 12994 to the program location and in standard locations 12995 (/usr/local/share/x11vnc/classes, etc). Under -ssl or 12996 -stunnel the ssl classes subdirectory is sought. 12997 -http_ssl As -http, but force lookup for ssl classes subdir. 12998 12999 Note that for HTTPS, single-port Java applet delivery 13000 you can set X11VNC_HTTPS_DOWNLOAD_WAIT_TIME to the 13001 max number of seconds to wait for the applet download 13002 to finish. The default is 15. 13003 13004 -avahi Use the Avahi/mDNS ZeroConf protocol to advertise 13005 this VNC server to the local network. (Related terms: 13006 Rendezvous, Bonjour). Depending on your setup, you 13007 may need to start avahi-daemon and open udp port 5353 13008 in your firewall. 13009 13010 You can set X11VNC_AVAHI_NAME, X11VNC_AVAHI_HOST, 13011 and/or X11VNC_AVAHI_PORT environment variables 13012 to override the default values. For example: 13013 -env X11VNC_AVAHI_NAME=wally 13014 13015 If the avahi API cannot be found at build time, a helper 13016 program like avahi-publish(1) or dns-sd(1) will be tried 13017 13018 -mdns Same as -avahi. 13019 -zeroconf Same as -avahi. 13020 13021 -connect string For use with "vncviewer -listen" reverse connections. 13022 If "string" has the form "host" or "host:port" 13023 the connection is made once at startup. 13024 13025 Use commas for a list of host's and host:port's. 13026 E.g. -connect host1,host2 or host1:0,host2:5678. 13027 Note that to reverse connect to multiple hosts at the 13028 same time you will likely need to also supply: -shared 13029 13030 Note that unlike most vnc servers, x11vnc will require a 13031 password for reverse as well as for forward connections. 13032 (provided password auth has been enabled, -rfbauth, etc) 13033 If you do not want to require a password for reverse 13034 connections set X11VNC_REVERSE_CONNECTION_NO_AUTH=1 in 13035 your environment before starting x11vnc. 13036 13037 If "string" contains "/" it is instead interpreted 13038 as a file to periodically check for new hosts. 13039 The first line is read and then the file is truncated. 13040 Be careful about the location of this file if x11vnc 13041 is running as root (e.g. via gdm(1), etc). 13042 13043 13044 Repeater mode: Some services provide an intermediate 13045 "vnc repeater": http://www.uvnc.com/addons/repeater.html 13046 (and also http://koti.mbnet.fi/jtko/ for linux port) 13047 that acts as a proxy/gateway. Modes like these require 13048 an initial string to be sent for the reverse connection 13049 before the VNC protocol is started. Here are the ways 13050 to do this: 13051 13052 -connect pre=some_string+host:port 13053 -connect pre128=some_string+host:port 13054 -connect repeater=ID:1234+host:port 13055 -connect repeater=23.45.67.89::5501+host:port 13056 13057 SSVNC notation is also supported: 13058 13059 -connect repeater://host:port+ID:1234 13060 13061 As with normal -connect usage, if the repeater port is 13062 not supplied 5500 is assumed. 13063 13064 The basic idea is between the special tag, e.g. "pre=" 13065 and "+" is the pre-string to be sent. Note that in 13066 this case host:port is the repeater server, NOT the 13067 vnc viewer. Somehow the pre-string tells the repeater 13068 server how to find the vnc viewer and connect you to it. 13069 13070 In the case pre=some_string+host:port, "some_string" 13071 is simply sent. In the case preNNN=some_string+host:port 13072 "some_string" is sent in a null padded buffer of 13073 length NNN. repeater= is the same as pre250=, this is 13074 the ultravnc repeater buffer size. 13075 13076 Strings like "\n" and "\r", etc. are expanded to 13077 newline and carriage return. "\c" is expanded to 13078 "," since the connect string is comma separated. 13079 13080 See also the -proxy option below for additional ways 13081 to plumb reverse connections. 13082 13083 Reverse SSL: using -connect in -ssl mode makes x11vnc 13084 act as an SSL client (initiates SSL connection) rather 13085 than an SSL server. The idea is x11vnc might be 13086 connecting to stunnel on the viewer side with the 13087 viewer in listening mode. If you do not want this 13088 behavior, use -env X11VNC_DISABLE_SSL_CLIENT_MODE=1. 13089 With this the viewer side can act as the SSL client 13090 as it normally does for forward connections. 13091 13092 Reverse SSL Repeater mode: This will work, but note 13093 that if the VNC Client does any sort of a 'Fetch Cert' 13094 action before connecting, then the Repeater will 13095 likely drop the connection and both sides will need 13096 to restart. Consider the use of -connect_or_exit 13097 and -loop300,2 to have x11vnc reconnect once to the 13098 repeater after the fetch. You will probably also want 13099 to supply -sslonly to avoid x11vnc thinking the delay 13100 in response means the connection is VeNCrypt. The env 13101 var X11VNC_DISABLE_SSL_CLIENT_MODE=1 discussed above 13102 may also be useful (i.e. the viewer can do a forward 13103 connection as it normally does.) 13104 13105 IPv6: as of x11vnc 0.9.10 the -connect option should 13106 connect to IPv6 hosts properly. If there are problems 13107 you can disable IPv6 by setting -DX11VNC_IPV6=0 13108 in CPPFLAGS when configuring. If there problems 13109 connecting to IPv6 hosts consider a relay like the 13110 included inet6to4 script or the -proxy option. 13111 13112 -connect_or_exit str As with -connect, except if none of the reverse 13113 connections succeed, then x11vnc shuts down immediately 13114 13115 An easier to type alias for this option is '-coe' 13116 13117 By the way, if you do not want x11vnc to listen on 13118 ANY interface use -rfbport 0 which is handy for the 13119 -connect_or_exit mode. 13120 13121 -proxy string Use proxy in string (e.g. host:port) as a proxy for 13122 making reverse connections (-connect or -connect_or_exit 13123 options). 13124 13125 Web proxies are supported, but note by default most of 13126 them only support destination connections to ports 443 13127 or 563, so this might not be very useful (the viewer 13128 would need to listen on that port or the router would 13129 have to do a port redirection). 13130 13131 A web proxy may be specified by either "host:port" 13132 or "http://host:port" (the port is required even if 13133 it is the common choices 80 or 8080) 13134 13135 SOCKS4, SOCKS4a, and SOCKS5 are also supported. 13136 SOCKS proxies normally do not have restrictions on the 13137 destination port number. 13138 13139 Use a format like this: socks://host:port or 13140 socks5://host:port. Note that ssh -D does not support 13141 SOCKS4a, so use socks5://. For socks:// SOCKS4 is used 13142 on a numerical IP and "localhost", otherwise SOCKS4a 13143 is used (and so the proxy tries to do the DNS lookup). 13144 13145 An experimental mode is "-proxy http://host:port/..." 13146 Note the "/" after the port that distinguishes it from 13147 a normal web proxy. The port must be supplied even if 13148 it is the default 80. For this mode a GET is done to 13149 the supplied URL with the string host=H&port=P appended. 13150 H and P will be the -connect reverse connect host 13151 and port. Use the string "__END__" to disable the 13152 appending. The basic idea here is that maybe some cgi 13153 script provides the actual viewer hookup and tunnelling. 13154 How to actually achieve this within cgi, php, etc. is 13155 not clear... A custom web server or apache module 13156 would be straight-forward. 13157 13158 Another experimental mode is "-proxy ssh://user@host" 13159 in which case a SSH tunnel is used for the proxying. 13160 "user@" is not needed unless your unix username is 13161 different on "host". For a non-standard SSH port 13162 use ssh://user@host:port. If proxies are chained (see 13163 next paragraph) then the ssh one must be the first one. 13164 If ssh-agent is not active, then the ssh password needs 13165 to be entered in the terminal where x11vnc is running. 13166 Examples: 13167 13168 -connect localhost:0 -proxy ssh://me@friends-pc:2222 13169 13170 -connect snoopy:0 -proxy ssh://ssh.company.com 13171 13172 Multiple proxies may be chained together in case one 13173 needs to ricochet off of a number of hosts to finally 13174 reach the VNC viewer. Up to 3 may be chained, separate 13175 them by commas in the order they are to be connected to. 13176 E.g.: http://host1:port1,socks5://host2:port2 or three 13177 like: first,second,third 13178 13179 IPv6: as of x11vnc 0.9.10 the -proxy option should 13180 connect to IPv6 hosts properly. If there are problems 13181 you can disable IPv6 by setting -DX11VNC_IPV6=0 13182 in CPPFLAGS when configuring. If there problems 13183 connecting to IPv6 hosts consider a relay like the 13184 included inet6to4 script. 13185 13186 -vncconnect Monitor the VNC_CONNECT X property set by the standard 13187 -novncconnect VNC program vncconnect(1). When the property is 13188 set to "host" or "host:port" establish a reverse 13189 connection. Using xprop(1) instead of vncconnect may 13190 work (see the FAQ). The -remote control mechanism uses 13191 X11VNC_REMOTE channel, and this option disables/enables 13192 it as well. Default: -vncconnect 13193 13194 To use different names for these X11 properties (e.g. to 13195 have separate communication channels for multiple 13196 x11vnc's on the same display) set the VNC_CONNECT or 13197 X11VNC_REMOTE env. vars. to the string you want, for 13198 example: -env X11VNC_REMOTE=X11VNC_REMOTE_12345 13199 Both sides of the channel must use the same unique name. 13200 The same can be done for the internal X11VNC_TICKER 13201 property (heartbeat and timestamp) if desired. 13202 13203 -allow host1[,host2..] Only allow client connections from hosts matching 13204 the comma separated list of hostnames or IP addresses. 13205 Can also be a numerical IP prefix, e.g. "192.168.100." 13206 to match a simple subnet, for more control build 13207 LibVNCServer with libwrap support (See the FAQ). If the 13208 list contains a "/" it instead is a interpreted 13209 as a file containing addresses or prefixes that is 13210 re-read each time a new client connects. Lines can be 13211 commented out with the "#" character in the usual way. 13212 13213 -allow applies in -ssl mode, but not in -stunnel mode. 13214 13215 IPv6: as of x11vnc 0.9.10 a host can be specified 13216 in IPv6 numerical format, e.g. 2001:4860:b009::93. 13217 13218 -localhost Basically the same as "-allow 127.0.0.1". 13219 13220 Note: if you want to restrict which network interface 13221 x11vnc listens on, see the -listen option below. 13222 E.g. "-listen localhost" or "-listen 192.168.3.21". 13223 As a special case, the option "-localhost" implies 13224 "-listen localhost". 13225 13226 A rare case, but for non-localhost -listen usage, if 13227 you use the remote control mechanism (-R) to change 13228 the -listen interface you may need to manually adjust 13229 the -allow list (and vice versa) to avoid situations 13230 where no connections (or too many) are allowed. 13231 13232 If you do not want x11vnc to listen on ANY interface 13233 (evidently you are using -connect or -connect_or_exit, 13234 or plan to use remote control: -R connect:host), use 13235 -rfbport 0 13236 13237 IPv6: if IPv6 is supported, this option automatically 13238 implies the IPv6 loopback address '::1' as well. 13239 13240 -unixsock str Listen on the unix socket (AF_UNIX) 'str' 13241 for connections. This mode is for either local 13242 connections or a tunnel endpoint where one wants the 13243 file permission of the unix socket file to determine 13244 what can connect to it. (This currently requires an 13245 edit to libvnserver/rfbserver.c: comment out lines 310 13246 and 311, 'close(sock)' and 'return NULL' in rfbserver.c 13247 after the setsockopt() call.) Note that to disable all 13248 tcp listening ports specify '-rfbport 0' and should be 13249 useful with this mode. Example: 13250 mkdir ~/s; chmod 700 ~/s; 13251 x11vnc -unixsock ~/s/mysock -rfbport 0 ... 13252 The SSVNC unix vncviewer can connect to unix sockets. 13253 13254 -listen6 str When in IPv6 listen mode "-6", listen only on the 13255 network interface with address "str". It also works 13256 for link scope addresses (fe80::219:dbff:fee5:3f92%eth0) 13257 and IPv6 hostname strings (e.g. ipv6.google.com.) 13258 Use LibVNCServer -listen option for the IPv4 interface. 13259 13260 -nolookup Do not use gethostbyname() or gethostbyaddr() to look up 13261 host names or IP numbers. Use this if name resolution 13262 is incorrectly set up and leads to long pauses as name 13263 lookups time out, etc. 13264 13265 -input string Fine tuning of allowed user input. If "string" does 13266 not contain a comma "," the tuning applies only to 13267 normal clients. Otherwise the part before "," is 13268 for normal clients and the part after for view-only 13269 clients. "K" is for Keystroke input, "M" for 13270 Mouse-motion input, "B" for Button-click input, "C" 13271 is for Clipboard input, and "F" is for File transfer 13272 (ultravnc only). Their presence in the string enables 13273 that type of input. E.g. "-input M" means normal 13274 users can only move the mouse and "-input KMBCF,M" 13275 lets normal users do anything and enables view-only 13276 users to move the mouse. This option is ignored when 13277 a global -viewonly is in effect (all input is discarded 13278 in that case). 13279 13280 -grabkbd When VNC viewers are connected, attempt to the grab 13281 the keyboard so a (non-malicious) user sitting at the 13282 physical display is not able to enter keystrokes. 13283 This method uses XGrabKeyboard(3X11) and so it is 13284 not secure and does not rule out the person at the 13285 physical display injecting keystrokes by flooding the 13286 server with them, grabbing the keyboard himself, etc. 13287 Some degree of cooperation from the person at the 13288 display is assumed. This is intended for remote 13289 help-desk or educational usage modes. 13290 13291 Note: on some recent (12/2010) X servers and/or 13292 desktops, -grabkbd no longer works: it prevents the 13293 window manager from resizing windows and similar things. 13294 Try -ungrabboth below (might not work.) 13295 13296 -grabptr As -grabkbd, but for the mouse pointer using 13297 XGrabPointer(3X11). Unfortunately due to the way the X 13298 server works, the mouse can still be moved around by the 13299 user at the physical display, but he will not be able to 13300 change window focus with it. Also some window managers 13301 that call XGrabServer(3X11) for resizes, etc, will 13302 act on the local user's input. Again, some degree of 13303 cooperation from the person at the display is assumed. 13304 13305 -ungrabboth Whenever there is any input (either keyboard or 13306 pointer), ungrab *both* the keyboard and the pointer 13307 while injecting the synthetic input. This is to allow 13308 window managers, etc. a chance to grab. 13309 13310 -grabalways Apply both -grabkbd and -grabptr even when no VNC 13311 viewers are connected. If you only want one of them, 13312 use the -R remote control to turn the other back on, 13313 e.g. -R nograbptr. 13314 13315 -viewpasswd string Supply a 2nd password for view-only logins. The -passwd 13316 (full-access) password must also be supplied. 13317 13318 -passwdfile filename Specify the LibVNCServer password via the first line 13319 of the file "filename" (instead of via -passwd on 13320 the command line where others might see it via ps(1)). 13321 13322 See the descriptions below for how to supply multiple 13323 passwords, view-only passwords, to specify external 13324 programs for the authentication, and other features. 13325 13326 If the filename is prefixed with "rm:" it will be 13327 removed after being read. Perhaps this is useful in 13328 limiting the readability of the file. In general, the 13329 password file should not be readable by untrusted users 13330 (BTW: neither should the VNC -rfbauth file: it is NOT 13331 encrypted, only obscured with a fixed key). 13332 13333 If the filename is prefixed with "read:" it will 13334 periodically be checked for changes and reread. It is 13335 guaranteed to be reread just when a new client connects 13336 so that the latest passwords will be used. 13337 13338 If "filename" is prefixed with "cmd:" then the 13339 string after the ":" is run as an external command: 13340 the output of the command will be interpreted as if it 13341 were read from a password file (see below). If the 13342 command does not exit with 0, then x11vnc terminates 13343 immediately. To specify more than 1000 passwords this 13344 way set X11VNC_MAX_PASSWDS before starting x11vnc. 13345 The environment variables are set as in -accept. 13346 13347 Note that due to the VNC protocol only the first 8 13348 characters of a password are used (DES key). 13349 13350 If "filename" is prefixed with "custom:" then a 13351 custom password checker is supplied as an external 13352 command following the ":". The command will be run 13353 when a client authenticates. If the command exits with 13354 0 the client is accepted, otherwise it is rejected. 13355 The environment variables are set as in -accept. 13356 13357 The standard input to the custom command will be a 13358 decimal digit "len" followed by a newline. "len" 13359 specifies the challenge size and is usually 16 (the 13360 VNC spec). Then follows len bytes which is the random 13361 challenge string that was sent to the client. This is 13362 then followed by len more bytes holding the client's 13363 response (i.e. the challenge string encrypted via DES 13364 with the user password in the standard situation). 13365 13366 The "custom:" scheme can be useful to implement 13367 dynamic passwords or to implement methods where longer 13368 passwords and/or different encryption algorithms 13369 are used. The latter will require customizing the VNC 13370 client as well. One could create an MD5SUM based scheme 13371 for example. 13372 13373 File format for -passwdfile: 13374 13375 If multiple non-blank lines exist in the file they are 13376 all taken as valid passwords. Blank lines are ignored. 13377 Password lines may be "commented out" (ignored) if 13378 they begin with the character "#" or the line contains 13379 the string "__SKIP__". Lines may be annotated by use 13380 of the "__COMM__" string: from it to the end of the 13381 line is ignored. An empty password may be specified 13382 via the "__EMPTY__" string on a line by itself (note 13383 your viewer might not accept empty passwords). 13384 13385 If the string "__BEGIN_VIEWONLY__" appears on a 13386 line by itself, the remaining passwords are used for 13387 viewonly access. For compatibility, as a special case 13388 if the file contains only two password lines the 2nd 13389 one is automatically taken as the viewonly password. 13390 Otherwise the "__BEGIN_VIEWONLY__" token must be 13391 used to have viewonly passwords. (tip: make the 3rd 13392 and last line be "__BEGIN_VIEWONLY__" to have 2 13393 full-access passwords) 13394 13395 -showrfbauth filename Print to the screen the obscured VNC password kept in 13396 the rfbauth file "filename" and then exit. 13397 13398 -unixpw [list] Use Unix username and password authentication. x11vnc 13399 will use the su(1) program to verify the user's 13400 password. [list] is an optional comma separated list 13401 of allowed Unix usernames. If the [list] string begins 13402 with the character "!" then the entire list is taken 13403 as an exclude list. See below for per-user options 13404 that can be applied. 13405 13406 A familiar "login:" and "Password:" dialog is 13407 presented to the user on a black screen inside the 13408 vncviewer. The connection is dropped if the user fails 13409 to supply the correct password in 3 tries or does not 13410 send one before a 45 second timeout. Existing clients 13411 are view-only during this period. 13412 13413 If the first character received is "Escape" then the 13414 unix username will not be displayed after "login:" 13415 as it is typed. This could be of use for VNC viewers 13416 that automatically type the username and password. 13417 13418 Since the detailed behavior of su(1) can vary from 13419 OS to OS and for local configurations, test the mode 13420 before deployment to make sure it is working properly. 13421 x11vnc will attempt to be conservative and reject a 13422 login if anything abnormal occurs. 13423 13424 One case to note: FreeBSD and the other BSD's by 13425 default it is impossible for the user running x11vnc to 13426 validate his *own* password via su(1) (commenting out 13427 the pam_self.so entry in /etc/pam.d/su eliminates this 13428 behavior). So the x11vnc login will always *FAIL* for 13429 this case (even when the correct password is supplied). 13430 13431 A possible workaround for this on *BSD would be to 13432 start x11vnc as root with the "-users +nobody" option 13433 to immediately switch to user nobody where the su'ing 13434 will proceed normally. 13435 13436 Another source of potential problems are PAM modules 13437 that prompt for extra info, e.g. password aging modules. 13438 These logins will fail as well even when the correct 13439 password is supplied. 13440 13441 **IMPORTANT**: to prevent the Unix password being sent 13442 in *clear text* over the network, one of two schemes 13443 will be enforced: 1) the -ssl builtin SSL mode, or 2) 13444 require both -localhost and -stunnel be enabled. 13445 13446 Method 1) ensures the traffic is encrypted between 13447 viewer and server. A PEM file will be required, see the 13448 discussion under -ssl below (under some circumstances 13449 a temporary one can be automatically generated). 13450 13451 Method 2) requires the viewer connection to appear 13452 to come from the same machine x11vnc is running on 13453 (e.g. from a ssh -L port redirection). And that the 13454 -stunnel SSL mode be used for encryption over the 13455 network. (see the description of -stunnel below). 13456 13457 Note: as a convenience, if you ssh(1) in and start 13458 x11vnc it will check if the environment variable 13459 SSH_CONNECTION is set and appears reasonable. If it 13460 does, then the -ssl or -stunnel requirement will be 13461 dropped since it is assumed you are using ssh for the 13462 encrypted tunnelling. -localhost is still enforced. 13463 Use -ssl or -stunnel to force SSL usage even if 13464 SSH_CONNECTION is set. 13465 13466 To override the above restrictions you can set 13467 environment variables before starting x11vnc: 13468 13469 Set UNIXPW_DISABLE_SSL=1 to disable requiring either 13470 -ssl or -stunnel (as under SSH_CONNECTION.) Evidently 13471 you will be using a different method to encrypt the 13472 data between the vncviewer and x11vnc: perhaps ssh(1) 13473 or an IPSEC VPN. -localhost is still enforced (however, 13474 see the next paragraph.) 13475 13476 Set UNIXPW_DISABLE_LOCALHOST=1 to disable the -localhost 13477 requirement in -unixpw modes. One should never do this 13478 (i.e. allow the Unix passwords to be sniffed on the 13479 network.) This also disables the localhost requirement 13480 for reverse connections (see below.) 13481 13482 Note that use of -localhost with ssh(1) (and no -unixpw) 13483 is roughly the same as requiring a Unix user login 13484 (since a Unix password or the user's public key 13485 authentication is used by sshd on the machine where 13486 x11vnc runs and only local connections from that machine 13487 are accepted). 13488 13489 Regarding reverse connections (e.g. -R connect:host 13490 and -connect host), when the -localhost constraint is 13491 in effect then reverse connections can only be used 13492 to connect to the same machine x11vnc is running on 13493 (default port 5500). Please use a ssh or stunnel port 13494 redirection to the viewer machine to tunnel the reverse 13495 connection over an encrypted channel. 13496 13497 In -inetd mode the Method 1) will be enforced (not 13498 Method 2). With -ssl in effect reverse connections 13499 are disabled. If you override this via env. var, be 13500 sure to also use encryption from the viewer to inetd. 13501 Tip: you can also have your own stunnel spawn x11vnc 13502 in -inetd mode (thereby bypassing inetd). See the FAQ 13503 for details. 13504 13505 The user names in the comma separated [list] may have 13506 per-user options after a ":", e.g. "fred:opts" 13507 where "opts" is a "+" separated list of 13508 "viewonly", "fullaccess", "input=XXXX", or 13509 "deny", e.g. "karl,wally:viewonly,boss:input=M". 13510 For "input=" it is the K,M,B,C described under -input. 13511 13512 If an item in the list is "*" that means those 13513 options apply to all users. It ALSO implies all users 13514 are allowed to log in after supplying a valid password. 13515 Use "deny" to explicitly deny some users if you use 13516 "*" to set a global option. If [list] begins with the 13517 "!" character then "*" is ignored for checking if 13518 the user is allowed, but the option values associated 13519 with it do apply as normal. 13520 13521 There are also some utilities for checking passwords 13522 if [list] starts with the "%" character. See the 13523 quick_pw() function for more details. Description: 13524 "%-" or "%stdin" means read one line from stdin. 13525 "%env" means it is in $UNIXPW env var. A leading 13526 "%/" or "%." means read the first line from the 13527 filename that follows after the % character. % by 13528 itself means prompt for the username and password. 13529 Otherwise: %user:pass E.g. -unixpw %fred:swordfish 13530 For the other cases user:pass is read from the indicated 13531 source. If the password is correct 'Y user' is printed 13532 and the program exit code is 0. If the password is 13533 incorrect it prints 'N user' and the exit code is 1. 13534 If there is some other error the exit code is 2. 13535 This feature enables x11vnc to be a general unix user 13536 password checking tool; it could be used from scripts 13537 or other programs. These % password checks also apply 13538 to the -unixpw_nis and -unixpw_cmd options. 13539 13540 For the % password check, if the env. var. UNIXPW_CMD 13541 is set to a command then it is run as the user (assuming 13542 the password is correct.) The output of the command is 13543 not printed, the program or script must manage that by 13544 some other means. The exit code of x11vnc will depend 13545 on the exit code of the command that is run. 13546 13547 Use -nounixpw to disable unixpw mode if it was enabled 13548 earlier in the cmd line (e.g. -svc mode) 13549 13550 -unixpw_nis [list] As -unixpw above, however do not use su(1) but rather 13551 use the traditional getpwnam(3) + crypt(3) method to 13552 verify passwords. All of the above -unixpw options and 13553 constraints apply. 13554 13555 This mode requires that the encrypted passwords be 13556 readable. Encrypted passwords stored in /etc/shadow 13557 will be inaccessible unless x11vnc is run as root. 13558 13559 This is called "NIS" mode simply because in most 13560 NIS setups user encrypted passwords are accessible 13561 (e.g. "ypcat passwd") by an ordinary user and so that 13562 user can authenticate ANY user. 13563 13564 NIS is not required for this mode to work (only that 13565 getpwnam(3) return the encrypted password is required), 13566 but it is unlikely it will work (as an ordinary user) 13567 for most modern environments unless NIS is available. 13568 On the other hand, when x11vnc is run as root it will 13569 be able to to access /etc/shadow even if NIS is not 13570 available (note running as root is often done when 13571 running x11vnc from inetd and xdm/gdm/kdm). 13572 13573 Looked at another way, if you do not want to use the 13574 su(1) method provided by -unixpw (i.e. su_verify()), you 13575 can run x11vnc as root and use -unixpw_nis. Any users 13576 with passwords in /etc/shadow can then be authenticated. 13577 13578 In -unixpw_nis mode, under no circumstances is x11vnc's 13579 user password verifying function based on su called 13580 (i.e. the function su_verify() that runs /bin/su 13581 in a pseudoterminal to verify passwords.) However, 13582 if -unixpw_nis is used in conjunction with the -find 13583 and -create -display WAIT:... modes then, if x11vnc is 13584 running as root, /bin/su may be called externally to 13585 run the find or create commands. 13586 13587 -unixpw_cmd cmd As -unixpw above, however do not use su(1) but rather 13588 run the externally supplied command "cmd". The first 13589 line of its stdin will be the username and the second 13590 line the received password. If the command exits 13591 with status 0 (success) the VNC user will be accepted. 13592 It will be rejected for any other return status. 13593 13594 Dynamic passwords and non-unix passwords, e.g. LDAP, 13595 can be implemented this way by providing your own custom 13596 helper program. Note that the remote viewer is given 3 13597 tries to enter the correct password, and so the program 13598 may be called in a row that many (or more) times. 13599 13600 If a list of allowed users is needed to limit who can 13601 log in, use -unixpw [list] in addition to this option. 13602 13603 In FINDDISPLAY and FINDCREATEDISPLAY modes the "cmd" 13604 will also be run with the RFB_UNIXPW_CMD_RUN env. var. 13605 non-empty and set to the corresponding display 13606 find/create command. The first two lines of input are 13607 the username and passwd as in the normal case described 13608 above. To support FINDDISPLAY and FINDCREATEDISPLAY, 13609 "cmd" should run the requested command as the user 13610 (and most likely refusing to run it if the password is 13611 not correct.) Here is an example script (note it has 13612 a hardwired bogus password "abc"!) 13613 13614 #!/bin/sh 13615 # Example x11vnc -unixpw_cmd script. 13616 # Read the first two lines of stdin (user and passwd) 13617 read user 13618 read pass 13619 13620 debug=0 13621 if [ $debug = 1 ]; then 13622 echo "user: $user" 1>&2 13623 echo "pass: $pass" 1>&2 13624 env | egrep -i 'rfb|vnc' 1>&2 13625 fi 13626 13627 # Check if the password is valid. 13628 # (A real example would use ldap lookup, etc!) 13629 if [ "X$pass" != "Xabc" ]; then 13630 exit 1 # incorrect password 13631 fi 13632 13633 if [ "X$RFB_UNIXPW_CMD_RUN" = "X" ]; then 13634 exit 0 # correct password 13635 else 13636 # Run the requested command (finddisplay) 13637 if [ $debug = 1 ]; then 13638 echo "run: $RFB_UNIXPW_CMD_RUN" 1>&2 13639 fi 13640 exec /bin/su - "$user" -c "$RFB_UNIXPW_CMD_RUN" 13641 fi 13642 13643 In -unixpw_cmd mode, under no circumstances is x11vnc's 13644 user password verifying function based on su called 13645 (i.e. the function su_verify() that runs /bin/su in a 13646 pseudoterminal to verify passwords.) It is up to the 13647 supplied unixpw_cmd to do user switching if desired 13648 and if it has the permissions to do so. 13649 13650 -find Find the user's display using FINDDISPLAY. This 13651 is an alias for "-display WAIT:cmd=FINDDISPLAY". 13652 13653 Note: if a -display occurs later on the command line 13654 it will override the -find setting. 13655 13656 For this and the next few options see -display WAIT:... 13657 below for all of the details. 13658 13659 -finddpy Run the FINDDISPLAY program, print out the found 13660 display (if any) and exit. Output is like: DISPLAY=:0.0 13661 DISPLAY=:0.0,XPID=12345 or DISPLAY=:0.0,VT=7. XPID is 13662 the process ID of the found X server. VT is the Linux 13663 virtual terminal of the X server. 13664 -listdpy Have the FINDDISPLAY program list all of your displays 13665 (i.e. all the X displays on the local machine that you 13666 have access rights to). x11vnc then exits. 13667 13668 -findauth [disp] Apply the -find/-finddpy heuristics to try to guess 13669 the XAUTHORITY file for DISPLAY 'disp'. If 'disp' 13670 is not supplied, then the value in the -display on 13671 the cmdline is used; failing that $DISPLAY is used; 13672 and failing that ":0" is used. x11vnc then exits. 13673 13674 If nothing is printed out, that means no XAUTHORITY was 13675 found for 'disp'; i.e. failure. If "XAUTHORITY=" 13676 is printed out, that means use the default (i.e. do 13677 not set XAUTHORITY). If "XAUTHORITY=/path/to/file" 13678 is printed out, then use that file. 13679 13680 XDM/GDM/KDM: if you are running x11vnc as root and want 13681 to find the XAUTHORITY before anyone has logged into an 13682 X session yet, use: x11vnc -env FD_XDM=1 -findauth ... 13683 (This will also find the XAUTHORITY if a user is already 13684 logged into the X session.) When running as root, 13685 FD_XDM=1 will be tried if the initial -findauth fails. 13686 13687 -create First try to find the user's display using FINDDISPLAY, 13688 if that doesn't succeed create an X session via the 13689 FINDCREATEDISPLAY method. This is an alias for 13690 "-display WAIT:cmd=FINDCREATEDISPLAY-Xvfb". 13691 13692 Note: if a -display occurs later on the command line 13693 it will override the -create setting. 13694 13695 SSH NOTE: for both -find and -create you can (should!) 13696 add the "-localhost" option to force SSH tunnel access. 13697 13698 -xdummy As in -create, except Xdummy instead of Xvfb. 13699 -xvnc As in -create, except Xvnc instead of Xvfb. 13700 -xvnc_redirect As in -create, except Xvnc.redirect instead of Xvfb. 13701 -xdummy_xvfb Sets WAIT:cmd=FINDCREATEDISPLAY-Xdummy,Xvfb 13702 13703 -create_xsrv str Sets WAIT:cmd=FINDCREATEDISPLAY-<str> Can be on cmdline 13704 after anything that sets WAIT:.. and other things 13705 (e.g. -svc, -xdmsvc) to adjust the X server list. 13706 Example: -svc ... -create_xsrv Xdummy,X 13707 13708 -svc Terminal services mode based on SSL access. Alias for 13709 -display WAIT:cmd=FINDCREATEDISPLAY-Xvfb -unixpw -users 13710 unixpw= -ssl SAVE Also "-service". 13711 13712 Note: if a -display, -unixpw, -users, or -ssl occurs 13713 later on the command line it will override the -svc 13714 setting. 13715 13716 -svc_xdummy As -svc except Xdummy instead of Xvfb. 13717 -svc_xvnc As -svc except Xvnc instead of Xvfb. 13718 -svc_xdummy_xvfb As -svc with Xdummy,Xvfb. 13719 13720 -xdmsvc Display manager Terminal services mode based on SSL. 13721 Alias for -display WAIT:cmd=FINDCREATEDISPLAY-Xvfb.xdmcp 13722 -unixpw -users unixpw= -ssl SAVE Also "-xdm_service". 13723 13724 Note: if a -display, -unixpw, -users, or -ssl occurs 13725 later on the command line it will override the -xdmsvc 13726 setting. 13727 13728 To create a session a user will have to first log in 13729 to the -unixpw dialog and then log in again to the 13730 XDM/GDM/KDM prompt. Subsequent re-connections will 13731 only require the -unixpw password. See the discussion 13732 under -display WAIT:... for more details about XDM, 13733 etc configuration. 13734 13735 Remember to enable XDMCP in the xdm-config, gdm.conf, 13736 or kdmrc configuration file. See -display WAIT: for 13737 more info. 13738 13739 -sshxdmsvc Display manager Terminal services mode based on SSH. 13740 Alias for -display WAIT:cmd=FINDCREATEDISPLAY-Xvfb.xdmcp 13741 -localhost. 13742 13743 The -localhost option constrains connections to come 13744 in via a SSH tunnel (which will require a login). 13745 To create a session a user will also have to log into 13746 the XDM GDM KDM prompt. Subsequent re-connections will 13747 only only require the SSH login. See the discussion 13748 under -display WAIT:... for more details about XDM, 13749 etc configuration. 13750 13751 Remember to enable XDMCP in the xdm-config, gdm.conf, 13752 or kdmrc configuration file. See -display WAIT: for 13753 more info. 13754 13755 -unixpw_system_greeter Present a "Press 'Escape' for System Greeter" option 13756 to the connecting VNC client in combined -unixpw 13757 and xdmcp FINDCREATEDISPLAY modes (e.g. -xdmsvc). 13758 13759 Normally in a -unixpw mode the VNC client must 13760 supply a valid username and password to gain access. 13761 However, if -unixpw_system_greeter is supplied AND 13762 the FINDCREATEDISPLAY command matches 'xdmcp', then 13763 the user has the option to press Escape and then get a 13764 XDM/GDM/KDM login/greeter panel instead. They will then 13765 supply a username and password directly to the greeter. 13766 13767 Otherwise, in xdmcp FINDCREATEDISPLAY mode the user 13768 must supply his username and password TWICE. First to 13769 the initial unixpw login dialog, and second to the 13770 subsequent XDM/GDM/KDM greeter. Note that if the user 13771 re-connects and supplies his username and password in 13772 the unixpw dialog the xdmcp greeter is skipped and 13773 he is connected directly to his existing X session. 13774 So the -unixpw_system_greeter option avoids the extra 13775 password at X session creation time. 13776 13777 Example: x11vnc -xdmsvc -unixpw_system_greeter 13778 See -unixpw and -display WAIT:... for more info. 13779 13780 The special options after a colon at the end of the 13781 username (e.g. user:solid) described under -display 13782 WAIT: are also applied in this mode if they are typed 13783 in before the user hits Escape. The username is ignored 13784 but the colon options are not. 13785 13786 The default message is 2 lines in a small font, set 13787 the env. var. X11VNC_SYSTEM_GREETER1=true for a 1 line 13788 message in a larger font. 13789 13790 If the user pressed Escape the FINDCREATEDISPLAY command 13791 will be run with the env. var. X11VNC_XDM_ONLY=1. 13792 13793 Remember to enable XDMCP in the xdm-config, gdm.conf, 13794 or kdmrc configuration file. See -display WAIT: for 13795 more info. 13796 13797 -redirect port As in FINDCREATEDISPLAY-Xvnc.redirect mode except 13798 redirect immediately (i.e. without X session finding 13799 or creation) to a VNC server listening on port. You 13800 can also supply host:port to redirect to a different 13801 machine. 13802 13803 If 0 <= port < 200 it is taken as a VNC display (5900 is 13804 added to get the actual port), if port < 0 then -port 13805 is used. 13806 13807 Probably the only reason to use the -redirect option 13808 is in conjunction with SSL support, e.g. -ssl SAVE. 13809 This provides an easy way to add SSL encryption to a VNC 13810 server that does not support SSL (e.g. Xvnc or vnc.so) 13811 In fact, the protocol does not even need to be VNC, 13812 and so "-rfbport port1 -ssl SAVE -redirect host:port2" 13813 can act as a replacement for stunnel(1). 13814 13815 This mode only allows one redirected connection. 13816 The -forever option does not apply. Use -inetd or 13817 -loop for persistent service. 13818 13819 -display_WAIT :... A special usage mode for the normal -display option. 13820 Useful with -unixpw, but can be used independently 13821 of it. If the display string begins with WAIT: then 13822 x11vnc waits until a VNC client connects before opening 13823 the X display (or -rawfb device). 13824 13825 This could be useful for delaying opening the display 13826 for certain usage modes (say if x11vnc is started at 13827 boot time and no X server is running or users logged 13828 in yet). 13829 13830 If the string is, e.g. WAIT:0.0 or WAIT:1, i.e. "WAIT" 13831 in front of a normal X display, then that indicated 13832 display is used. 13833 13834 One can also insert a geometry between colons, e.g. 13835 WAIT:1280x1024:... to set the size of the display the 13836 VNC client first attaches to since some VNC viewers 13837 will not automatically adjust to a new framebuffer size. 13838 13839 A more interesting case is like this: 13840 13841 WAIT:cmd=/usr/local/bin/find_display 13842 13843 in which case the command after "cmd=" is run to 13844 dynamically work out the DISPLAY and optionally the 13845 XAUTHORITY data. The first line of the command output 13846 must be of the form DISPLAY=<xdisplay>. On Linux 13847 if the virtual terminal is known append ",VT=n" to 13848 this string and the chvt(1) program will also be run. 13849 Any remaining output is taken as XAUTHORITY data. 13850 It can be either of the form XAUTHORITY=<file> or raw 13851 xauthority data for the display. For example; 13852 13853 xauth extract - $DISPLAY" 13854 13855 NOTE: As specified in the previous paragraph, you can 13856 supply your own WAIT:cmd=... program or script, BUT 13857 there are two very useful *BUILT-IN* ones: FINDDISPLAY 13858 (alias -find above) and FINDCREATEDISPLAY (alias -create 13859 above.) Most people use these instead of creating 13860 their own script. Read the following (especially the 13861 BUILT-IN modes sections) to see how to configure these 13862 two useful builtin -display WAIT: modes. 13863 13864 In the case of -unixpw (and -unixpw_nis only if x11vnc 13865 is running as root), then the cmd= command is run 13866 as the user who just authenticated via the login and 13867 password prompt. 13868 13869 In the case of -unixpw_cmd, the commands will also be 13870 run as the logged-in user, as long as the user-supplied 13871 helper program supports RFB_UNIXPW_CMD_RUN (see the 13872 -unixpw_cmd option.) 13873 13874 Also in the case of -unixpw, the user logging in can 13875 place a colon at the end of her username and supply 13876 a few options: scale=, scale_cursor= (or sc=), solid 13877 (or so), id=, clear_mods (or cm), clear_keys (or 13878 ck), clear_all (or ca), repeat, speeds= (or sp=), 13879 readtimeout= (or rd=), viewonly (or vo), nodisplay= 13880 (or nd=), rotate= (or ro=), or noncache (or nc), 13881 all separated by commas if there is more than one. 13882 After the user logs in successfully, these options will 13883 be applied to the VNC screen. For example, 13884 13885 login: fred:scale=3/4,sc=1,repeat 13886 Password: ... 13887 13888 login: runge:sp=modem,rd=120,solid 13889 13890 for convenience m/n implies scale= e.g. fred:3/4 If you 13891 type and enter your password incorrectly, to retrieve 13892 your long "login:" line press the Up arrow once 13893 (before typing anything else). 13894 13895 Most of these colon options only apply to the builtin 13896 FINDDISPLAY and FINDCREATEDISPLAY modes, but note 13897 that they are passed to the extrenal command in the 13898 environment as well and so could be used. 13899 13900 In the login panel, press F1 to get a list of the 13901 available options that you can add after the username. 13902 13903 Another option is "geom=WxH" or "geom=WxHxD" (or 13904 ge=). This only has an effect in FINDCREATEDISPLAY 13905 mode when a virtual X server such as Xvfb is going 13906 to be created. It sets the width and height of 13907 the new display, and optionally the color depth as 13908 well. 13909 13910 You can also supply "gnome", "kde", "twm", 13911 "fvwm", "mwm", "dtwm", "wmaker", "xfce", 13912 "lxde", "enlightenment", "Xsession", or 13913 "failsafe" (same as "xterm") to have the created 13914 display use that mode for the user session. 13915 13916 Specify "tag=..." to set the unique FD_TAG desktop 13917 session tag described below. Note: this option will 13918 be ignored if the FD_TAG env. var. is already set or 13919 if the viewer-side supplied value is not completely 13920 composed of alphanumeric or '_' or '-' characters. 13921 13922 User preferences file: Instead of having the user type 13923 in geom=WxH,... etc. every time he logs in to find 13924 or create his X session, if you set FD_USERPREFS to 13925 a string that does not contain the "/" character, 13926 then the user's home directory is prepended to that 13927 string and if the file exists its first line is read 13928 and appended to any options he supplied at the login: 13929 prompt. For example -env FD_USERPREFS=.x11vnc_create 13930 and the user put "geom=1600x1200" in his 13931 ~/.x11vnc_create file. 13932 13933 To disable the option setting set the environment 13934 variable X11VNC_NO_UNIXPW_OPTS=1 before starting x11vnc. 13935 To set any other options, the user can use the gui 13936 (x11vnc -gui connect) or the remote control method 13937 (x11vnc -R opt:val) during his VNC session. 13938 13939 So we see the combination of -display WAIT:cmd=... and 13940 -unixpw allows automatic pairing of an unix 13941 authenticated VNC user with his desktop. This could 13942 be very useful on SunRays and also any system where 13943 multiple users share a given machine. The user does 13944 not need to remember special ports or passwords set up 13945 for his desktop and VNC. 13946 13947 A nice way to use WAIT:cmd=... is out of inetd(8) 13948 (it automatically forks a new x11vnc for each user). 13949 You can have the x11vnc inetd spawned process run as, 13950 say, root or nobody. When run as root (for either inetd 13951 or display manager), you can also supply the option 13952 "-users unixpw=" to have the x11vnc process switch to 13953 the user as well. Note: there will be a 2nd SSL helper 13954 process that will not switch, but it is only encoding 13955 and decoding the encrypted stream at that point. 13956 13957 BUILT-IN modes: 13958 13959 -- Automatic Finding of User X Sessions -- 13960 13961 As a special case, WAIT:cmd=FINDDISPLAY will run a 13962 script that works on most Unixes to determine a user's 13963 DISPLAY variable and xauthority data (see who(1)). 13964 13965 NOTE: The option "-find" is an alias for this mode. 13966 13967 To have this default script printed to stdout (e.g. for 13968 customization) run with WAIT:cmd=FINDDISPLAY-print To 13969 have the script run to print what display it would find 13970 use "-finddpy" or WAIT:cmd=FINDDISPLAY-run 13971 13972 The standard script runs xdpyinfo(1) run on potential 13973 displays. If your X server(s) have a login greeter 13974 that exclusively grabs the Xserver, then xdpyinfo 13975 blocks forever and this mode will not work. See 13976 www.karlrunge.com/x11vnc/faq.html#faq-display-manager 13977 for how to disable this for dtgreet on Solaris and 13978 possibly for other greeters. 13979 13980 In -find/cmd=FINDDISPLAY mode, if you set FD_XDM=1, 13981 e.g. 'x11vnc -env FD_XDM=1 -find ...' and x11vnc is 13982 running as root (e.g. inetd) then it will try to find 13983 the XAUTHORITY file of a running XDM/GDM/KDM login 13984 greeter (i.e. no user has logged into an X session yet.) 13985 13986 As another special case, WAIT:cmd=HTTPONCE will allow 13987 x11vnc to service one http request and then exit. 13988 This is usually done in -inetd mode to run on, say, 13989 port 5800 and allow the Java vncviewer to be downloaded 13990 by client web browsers. For example: 13991 13992 5815 stream tcp nowait root /usr/sbin/tcpd /.../x11vnc 13993 \ 13994 -inetd -q -http_ssl -prog /.../x11vnc \ 13995 -display WAIT:cmd=HTTPONCE 13996 13997 Where /.../x11vnc is the full path to x11vnc. 13998 It is used in the Apache SSL-portal example (see FAQ). 13999 14000 In this mode you can set X11VNC_SKIP_DISPLAY to a 14001 comma separated list of displays (e.g. ":0,:1") to 14002 ignore in the finding process. The ":" is optional. 14003 Ranges n-m e.g. 0-20 can also be supplied. This string 14004 can also be set by the connecting user via "nd=" 14005 using "+" instead of "," If "nd=all" or you set 14006 X11VNC_SKIP_DISPLAY=all then all display finding fails 14007 as if you set X11VNC_FINDDISPLAY_ALWAYS_FAILS=1 (below.) 14008 14009 On some systems lsof(1) can be very slow. Set the 14010 env. var. FIND_DISPLAY_NO_LSOF=1 to skip using lsof to 14011 try to find the Linux VT the X server is running on. 14012 set FIND_DISPLAY_NO_VT_FIND=1 to avoid looking at all. 14013 14014 -- Automatic Creation of User X Sessions -- 14015 14016 An interesting option is WAIT:cmd=FINDCREATEDISPLAY 14017 that is like FINDDISPLAY in that is uses the same method 14018 to find an existing display. However, if it does not 14019 find one it will try to *start* up an X server session 14020 for the user. This is the only time x11vnc tries to 14021 actually start up an X server. 14022 14023 NOTE: The option "-create" is an alias for this mode. 14024 14025 It will start looking for an open display number at :20 14026 Override via X11VNC_CREATE_STARTING_DISPLAY_NUMBER=n 14027 By default 80 X displays are allowed (i.e. going to :99) 14028 Override via X11VNC_CREATE_MAX_DISPLAYS=n 14029 14030 For its heuristics, the create display script sets 14031 LC_ALL=C so that command output is uniform. By default 14032 it will try to restore LC_ALL right before starting the 14033 user session. However, if you don't mind it keeping 14034 LC_ALL=C set the env. var.: X11VNC_CREATE_LC_ALL_C_OK=1 14035 14036 By default FINDCREATEDISPLAY will try Xvfb and then 14037 Xdummy: 14038 14039 The Xdummy wrapper is part of the x11vnc source code 14040 (x11vnc/misc/Xdummy) It should be available in PATH 14041 and have run "Xdummy -install" once to create the 14042 shared library. Xdummy only works on Linux. As of 14043 12/2009 it no longer needs to be run as root, and the 14044 default is to not run as root. In some circumstances 14045 permissions may require running it as root, in these 14046 cases specify FD_XDUMMY_RUN_AS_ROOT=1, this is the same 14047 as supplying -root to the Xdummy cmdline. 14048 14049 Xvfb is available on most platforms and does not 14050 require root. 14051 14052 An advantage of Xdummy over Xvfb is that Xdummy supports 14053 RANDR dynamic screen resizing. 14054 14055 When x11vnc exits (i.e. user disconnects) the X 14056 server session stays running in the background. 14057 The FINDDISPLAY will find it directly next time. 14058 The user must exit the X session in the usual way for 14059 it to terminate (or kill the X server process if all 14060 else fails). 14061 14062 To troubleshoot the FINDCREATEDISPLAY mechanism, 14063 set the following env. var. to an output log file, 14064 e.g -env CREATE_DISPLAY_OUTPUT=/tmp/mydebug.txt 14065 14066 So this is a somewhat odd mode for x11vnc in that it 14067 will start up and poll virtual X servers! This can 14068 be used from, say, inetd(8) to provide a means of 14069 definitely getting a desktop (either real or virtual) 14070 on the machine. E.g. a desktop service: 14071 14072 5900 stream tcp nowait root /usr/sbin/tcpd /.../x11vnc 14073 -inetd -q -http -ssl SAVE -unixpw -users unixpw=\ 14074 -passwd secret -prog /.../x11vnc \ 14075 -display WAIT:cmd=FINDCREATEDISPLAY 14076 14077 Where /.../x11vnc is the full path to x11vnc. 14078 14079 See the -svc/-service option alias above. 14080 14081 If for some reason you do not want x11vnc to ever 14082 try to find an existing display set the env. var 14083 X11VNC_FINDDISPLAY_ALWAYS_FAILS=1 (also -env ...) 14084 This is the same as setting X11VNC_SKIP_DISPLAY=all or 14085 supplying "nd=all" after "username:" 14086 14087 Use WAIT:cmd=FINDCREATEDISPLAY-print to print out the 14088 script that is used for this. 14089 14090 You can specify the preferred X server order via e.g., 14091 WAIT:cmd=FINDCREATEDISPLAY-Xdummy,Xvfb,X and/or leave 14092 out ones you do not want. The the case "X" means try 14093 to start up a real, hardware X server using xinit(1) 14094 or startx(1). If there is already an X server running 14095 the X case may only work on Linux (see startx(1)). 14096 14097 "Xvnc" will start up a VNC X server (real- 14098 or tight-vnc, e.g. use if Xvfb is not available). 14099 "Xsrv" will start up the server program in the 14100 variable "FD_XSRV" if it is non-empty. You can make 14101 this be a wrapper script if you like (it must handle :N, 14102 -geometry, and -depth and other X server options). 14103 14104 You can set the environment variable FD_GEOM (or 14105 X11VNC_CREATE_GEOM) to WxH or WxHxD to set the width 14106 and height and optionally the color depth of the 14107 created display. You can also set FD_SESS to be the 14108 session (short name of the windowmanager: kde, gnome, 14109 twm, failsafe, etc.). FD_OPTS contains extra options 14110 to pass to the X server. You can also set FD_PROG to 14111 be the full path to the session/windowmanager program. 14112 14113 More FD tricks: FD_CUPS=port or FD_CUPS=host:port 14114 will set the cups printing environment. Similarly for 14115 FD_ESD=port or FD_ESD=host:port for esddsp sound 14116 redirection. Set FD_EXTRA to a command to be run a 14117 few seconds after the X server starts up. Set FD_TAG 14118 to be a unique name for the session, it is set as an 14119 X property, that makes FINDDISPLAY only find sessions 14120 with that tag value. 14121 14122 Set FD_XDMCP_IF to the network interface that the 14123 display manager is running on; default is 'localhost' 14124 but you may need to set it to '::1' on some IPv6 only 14125 systems or misconfigured display managers. 14126 14127 If you want the FINDCREATEDISPLAY session to contact an 14128 XDMCP login manager (xdm/gdm/kdm) on the same machine, 14129 then use "Xvfb.xdmcp" instead of "Xvfb", etc. 14130 The user will have to supply his username and password 14131 one more time (but he gets to select his desktop type 14132 so that can be useful). For this to work, you will 14133 need to enable localhost XDMCP (udp port 177) for the 14134 display manager. This seems to be: 14135 14136 for gdm in gdm.conf: Enable=true in section [xdmcp] 14137 for kdm in kdmrc: Enable=true in section [Xdmcp] 14138 for xdm in xdm-config: DisplayManager.requestPort: 177 14139 14140 See the shorthand options above "-svc", "-xdmsvc" 14141 and "-sshxdmsvc" that specify the above options for 14142 some useful cases. 14143 14144 If you set the env. var WAITBG=1 x11vnc will go into 14145 the background once listening in wait mode. 14146 14147 Another special mode is FINDCREATEDISPLAY-Xvnc.redirect, 14148 (or FINDDISPLAY-Xvnc.redirect). In this case it will 14149 start up Xvnc as above if needed, but instead of 14150 polling it in its normal way, it simply does a socket 14151 redirection of the connected VNC viewer to the Xvnc. 14152 14153 So in Xvnc.redirect x11vnc does no VNC but merely 14154 transfers the data back and forth. This should be 14155 faster then x11vnc's polling method, but not as fast 14156 as connecting directly to the Xvnc with the VNC Viewer. 14157 The idea here is to take advantage of x11vnc's display 14158 finding/creating scheme, SSL, and perhaps a few others. 14159 Most of x11vnc's options do not apply in this mode. 14160 14161 Xvnc.redirect should also work for the vnc.so X server 14162 module for the h/w display however it will work only 14163 for finding the display and the user must already be 14164 logged into the X console. 14165 14166 -vencrypt mode The VeNCrypt extension to the VNC protocol allows 14167 encrypted SSL/TLS connections. If the -ssl mode is 14168 enabled, then VeNCrypt is enabled as well BY DEFAULT 14169 (they both use a SSL/TLS tunnel, only the protocol 14170 handshake is a little different.) 14171 14172 To control when and how VeNCrypt is used, specify the 14173 mode string. If mode is "never", then VeNCrypt is 14174 not used. If mode is "support" (the default) then 14175 VeNCrypt is supported. If mode is "only", then the 14176 similar and older ANONTLS protocol is not simultaneously 14177 supported. x11vnc's normal SSL mode (vncs://) will be 14178 supported under -ssl unless you set mode to "force". 14179 14180 If mode is prefixed with "nodh:", then Diffie Hellman 14181 anonymous key exchange is disabled. If mode is prefixed 14182 with "nox509:", then X509 key exchange is disabled. 14183 14184 To disable all Anonymous Diffie-Hellman access 14185 (susceptible to Man-In-The-Middle attack) you will need 14186 to supply "-vencrypt nodh:support -anontls never" 14187 or "-vencrypt nodh:only" 14188 14189 If mode is prefixed with "newdh:", then new Diffie 14190 Hellman parameters are generated for each connection 14191 (this can be time consuming: 1-60 secs; see -dhparams 14192 below for a faster way) rather than using the 14193 fixed values in the program. Using fixed, publicly 14194 known values is not known to be a security problem. 14195 This setting applies to ANONTLS as well. 14196 14197 Long example: -vencrypt newdh:nox509:support 14198 14199 Also, if mode is prefixed with "plain:", then 14200 if -unixpw mode is active the VeNCrypt "*Plain" 14201 username+passwd method is enabled for Unix logins. 14202 Otherwise in -unixpw mode the normal login panel is 14203 provided. 14204 14205 You *MUST* supply the -ssl option for VeNCrypt to 14206 be active. The -vencrypt option only fine-tunes its 14207 operation. 14208 14209 -anontls mode The ANONTLS extension to the VNC protocol allows 14210 encrypted SSL/TLS connections. If the -ssl mode is 14211 enabled, then ANONTLS is enabled as well BY DEFAULT 14212 (they both use a SSL/TLS tunnel, only the protocol 14213 handshake is a little different.) 14214 14215 ANONTLS is an older SSL/TLS mode introduced by vino. 14216 14217 It is referred to as 'TLS' for its registered VNC 14218 security-type name, but we use the more descriptive 14219 'ANONTLS' here because it provides only Anonymous 14220 Diffie-Hellman encrypted connections, and hence no 14221 possibility for certificate authentication. 14222 14223 To control when and how ANONTLS is used, specify the 14224 mode string. If mode is "never", then ANONTLS is not 14225 used. If mode is "support" (the default) then ANONTLS 14226 is supported. If mode is "only", then the similar 14227 VeNCrypt protocol is not simultaneously supported. 14228 x11vnc's normal SSL mode (vncs://) will be supported 14229 under -ssl unless you set mode to "force". 14230 14231 If mode is prefixed with "newdh:", then new Diffie 14232 Hellman parameters are generated for each connection 14233 (this can be time consuming: 1-60 secs; see -dhparams 14234 below for a faster way) rather than using the 14235 fixed values in the program. Using fixed, publicly 14236 known values is not known to be a security problem. 14237 This setting applies to VeNCrypt as well. See the 14238 description of "plain:" under -vencrypt. 14239 14240 Long example: -anontls newdh:plain:support 14241 14242 You *MUST* supply the -ssl option for ANONTLS to 14243 be active. The -anontls option only fine-tunes its 14244 operation. 14245 14246 -sslonly Same as: "-vencrypt never -anontls never" i.e. it 14247 disables the VeNCrypt and ANONTLS encryption methods 14248 and only allows standard SSL tunneling. You must also 14249 supply the -ssl ... option (see below.) 14250 14251 14252 -dhparams file For some operations a set of Diffie Hellman parameters 14253 (prime and generator) is needed. If so, use the 14254 parameters in "file". In particular, the VeNCrypt and 14255 ANONTLS anonymous DH mode need them. By default a 14256 fixed set is used. If you do not want to do that you 14257 can specify "newdh:" to the -vencrypt and -anontls 14258 options to generate a new set each session. If that 14259 is too slow for you, use -dhparams file to a set you 14260 created manually via "openssl dhparam -out file 1024" 14261 14262 -nossl Disable the -ssl option (see below). Since -ssl is off 14263 by default -nossl would only be used on the commandline 14264 to unset any *earlier* -ssl option (or -svc...) 14265 14266 -ssl [pem] Use the openssl library (www.openssl.org) to provide a 14267 built-in encrypted SSL/TLS tunnel between VNC viewers 14268 and x11vnc. This requires libssl support to be 14269 compiled into x11vnc at build time. If x11vnc is not 14270 built with libssl support it will exit immediately when 14271 -ssl is prescribed. See the -stunnel option below for 14272 an alternative. 14273 14274 The VNC Viewer-side needs to support SSL/TLS as well. 14275 See this URL and also the discussion below for 14276 ideas on how to enable SSL support for the viewer: 14277 http://www.karlrunge.com/x11vnc/faq.html#faq-ssl-tun 14278 nel-viewers . x11vnc provides an SSL enabled Java 14279 viewer applet in the classes/ssl directory (-http or 14280 -httpdir options.) The SSVNC viewer package supports 14281 SSL tunnels too. 14282 14283 If the VNC Viewer supports VeNCrypt or ANONTLS (vino's 14284 encryption mode) they are also supported by the -ssl 14285 mode (see the -vencrypt and -anontls options for more 14286 info; use -sslonly to disable both of them.) 14287 14288 Use "-ssl /path/to/mycert.pem" to specify an SSL 14289 certificate file in PEM format to use to identify and 14290 provide a key for this server. See openssl(1) for more 14291 info about PEMs and the -sslGenCert and "-ssl SAVE" 14292 options below for how to create them. 14293 14294 The connecting VNC viewer SSL tunnel can (at its option) 14295 authenticate this server if it has the public key part 14296 of the certificate (or a common certificate authority, 14297 CA, is a more sophisticated way to verify this server's 14298 cert, see -sslGenCA below). This authentication is 14299 done to prevent Man-In-The-Middle attacks. Otherwise, 14300 if the VNC viewer simply accepts this server's key 14301 WITHOUT verification, the traffic is protected from 14302 passive sniffing on the network, but *NOT* from 14303 Man-In-The-Middle attacks. There are hacker tools 14304 like dsniff/webmitm and cain that implement SSL 14305 Man-In-The-Middle attacks. 14306 14307 If [pem] is empty or the string "SAVE" then the 14308 openssl(1) command must be available to generate the 14309 certificate the first time. A self-signed certificate 14310 is generated (see -sslGenCA and -sslGenCert for use 14311 of a Certificate Authority.) It will be saved to the 14312 file ~/.vnc/certs/server.pem. On subsequent calls if 14313 that file already exists it will be used directly. 14314 14315 Use "SAVE_NOPROMPT" to avoid being prompted to 14316 protect the generated key with a passphrase. However in 14317 -inetd and -bg modes there will be no prompting for a 14318 passphrase in either case. 14319 14320 If [pem] is "SAVE_PROMPT" the server.pem certificate 14321 will be created based on your answers to its prompts for 14322 all info such as OrganizationalName, CommonName, etc. 14323 14324 Use "SAVE-<string>" and "SAVE_PROMPT-<string>" 14325 to refer to the file ~/.vnc/certs/server-<string>.pem 14326 instead (it will be generated if it does not already 14327 exist). E.g. "SAVE-charlie" will store to the file 14328 ~/.vnc/certs/server-charlie.pem 14329 14330 Examples: x11vnc -ssl SAVE -display :0 ... 14331 x11vnc -ssl SAVE-someother -display :0 ... 14332 14333 If [pem] is "TMP" and the openssl(1) utility 14334 command exists in PATH, then a temporary, self-signed 14335 certificate will be generated for this session. If 14336 openssl(1) cannot be used to generate a temporary 14337 certificate x11vnc exits immediately. The temporary 14338 cert will be discarded when x11vnc exits. 14339 14340 If successful in using openssl(1) to generate a 14341 temporary certificate in "SAVE" or "TMP" creation 14342 modes, the public part of it will be displayed to stderr 14343 (e.g. one could copy it to the client-side to provide 14344 authentication of the server to VNC viewers.) 14345 14346 NOTE: In "TMP" mode, unless you safely copy the 14347 public part of the temporary Cert to the viewer for 14348 authenticate *every time* (unlikely...), then only 14349 passive sniffing attacks are prevented and you are 14350 still open to Man-In-The-Middle attacks. This is 14351 why the default "SAVE" mode is preferred (and more 14352 sophisticated CA mode too). Only with saved keys AND 14353 the VNC viewer authenticating them (via the public 14354 certificate), are Man-In-The-Middle attacks prevented. 14355 14356 If [pem] is "ANON" then the Diffie-Hellman anonymous 14357 key exchange method is used. In this mode there 14358 are *no* SSL certificates and so it is not possible 14359 to authenticate either the VNC server or VNC client. 14360 Thus only passive network sniffing attacks are avoided: 14361 the "ANON" method is susceptible to Man-In-The-Middle 14362 attacks. "ANON" is not recommended; instead use 14363 a SSL PEM you created or the default "SAVE" method. 14364 14365 See -ssldir below to use a directory besides the 14366 default ~/.vnc/certs 14367 14368 If your x11vnc binary was not compiled with OpenSSL 14369 library support, use of the -ssl option will induce an 14370 immediate failure and exit. For such binaries, consider 14371 using the -stunnel option for SSL encrypted connections. 14372 14373 Misc Info: In temporary cert creation mode "TMP", set 14374 the env. var. X11VNC_SHOW_TMP_PEM=1 to have x11vnc print 14375 out the entire certificate, including the PRIVATE KEY 14376 part, to stderr. There are better ways to get/save this 14377 info. See "SAVE" above and "-sslGenCert" below. 14378 14379 -ssltimeout n Set SSL read timeout to n seconds. In some situations 14380 (i.e. an iconified viewer in Windows) the viewer stops 14381 talking and the connection is dropped after the default 14382 timeout (25s for about the first minute, 43200s later). 14383 Set to zero to poll forever. Set to a negative value 14384 to use the builtin setting. 14385 14386 Note that this value does NOT apply to the *initial* ssl 14387 init connection. The default timeout for that is 20sec. 14388 Use -env SSL_INIT_TIMEOUT=n to modify it. 14389 14390 -sslnofail Exit at the first SSL connection failure. Useful when 14391 scripting SSL connections (e.g. x11vnc is started via 14392 ssh) and you do not want x11vnc waiting around for more 14393 connections, tying up ports, etc. 14394 14395 -ssldir dir Use "dir" as an alternate ssl certificate and key 14396 management toplevel directory. The default is 14397 ~/.vnc/certs 14398 14399 This directory is used to store server and other 14400 certificates and keys and also other materials. E.g. in 14401 the simplest case, "-ssl SAVE" will store the x11vnc 14402 server cert in dir/server.pem 14403 14404 Use of alternate directories via -ssldir allows you to 14405 manage multiple VNC Certificate Authority (CA) keys. 14406 Another use is if ~/.vnc/cert is on an NFS share you 14407 might want your certificates and keys to be on a local 14408 filesystem to prevent network snooping (for example 14409 -ssldir /var/lib/x11vnc-certs). 14410 14411 -ssldir affects nearly all of the other -ssl* options, 14412 e.g. -ssl SAVE, -sslGenCert, etc.. 14413 14414 -sslverify path For either of the -ssl or -stunnel modes, use "path" 14415 to provide certificates to authenticate incoming VNC 14416 *Client* connections (normally only the server is 14417 authenticated in SSL.) This can be used as a method 14418 to replace standard password authentication of clients. 14419 14420 If "path" is a directory it contains the client (or CA) 14421 certificates in separate files. If path is a file, 14422 it contains one or more certificates. See special tokens 14423 below. These correspond to the "CApath = dir" and 14424 "CAfile = file" stunnel options. See the stunnel(8) 14425 manpage for details. 14426 14427 Examples: 14428 x11vnc -ssl -sslverify ~/my.crt 14429 x11vnc -ssl -sslverify ~/my_pem_dir/ 14430 14431 Note that if path is a directory, it must contain 14432 the certs in separate files named like <HASH>.0, where 14433 the value of <HASH> is found by running the command 14434 "openssl x509 -hash -noout -in file.crt". Evidently 14435 one uses <HASH>.1 if there is a collision... 14436 14437 The the key-management utility "-sslCertInfo HASHON" 14438 and "-sslCertInfo HASHOFF" will create/delete these 14439 hashes for you automatically (via symlink) in the HASH 14440 subdirs it manages. Then you can point -sslverify to 14441 the HASH subdir. 14442 14443 Special tokens: in -ssl mode, if "path" is not a file or 14444 a directory, it is taken as a comma separated list of 14445 tokens that are interpreted as follows: 14446 14447 If a token is "CA" that means load the CA/cacert.pem 14448 file from the ssl directory. If a token is "clients" 14449 then all the files clients/*.crt in the ssl directory 14450 are loaded. Otherwise the file clients/token.crt 14451 is attempted to be loaded. As a kludge, use a token 14452 like ../server-foo to load a server cert if you find 14453 that necessary. 14454 14455 Use -ssldir to use a directory different from the 14456 ~/.vnc/certs default. 14457 14458 Note that if the "CA" cert is loaded you do not need 14459 to load any of the certs that have been signed by it. 14460 You will need to load any additional self-signed certs 14461 however. 14462 14463 Examples: 14464 x11vnc -ssl -sslverify CA 14465 x11vnc -ssl -sslverify self:fred,self:jim 14466 x11vnc -ssl -sslverify CA,clients 14467 14468 Usually "-sslverify CA" is the most effective. 14469 See the -sslGenCA and -sslGenCert options below for 14470 how to set up and manage the CA framework. 14471 14472 14473 14474 NOTE: the following utilities, -sslGenCA, -sslGenCert, 14475 -sslEncKey, -sslCertInfo, and -sslCRL are provided for 14476 completeness, but for casual usage they are overkill. 14477 14478 They provide VNC Certificate Authority (CA) key creation 14479 and server / client key generation and signing. So they 14480 provide a basic Public Key management framework for 14481 VNC-ing with x11vnc. (note that they require openssl(1) 14482 be installed on the system) 14483 14484 However, the simplest usage mode, "-ssl TMP" (where 14485 x11vnc automatically generates its own, self-signed, 14486 temporary key and the VNC viewers always accept it, 14487 e.g. accepting via a dialog box) is probably safe enough 14488 for most scenarios. CA management is not needed. 14489 14490 To protect against Man-In-The-Middle attacks the "TMP" 14491 mode can be improved by using "-ssl SAVE" (same as 14492 "-ssl", i.e. the default) to have x11vnc create a 14493 longer term self-signed certificate, and then (safely) 14494 copy the corresponding public key cert to the desired 14495 client machines (care must be taken the private key part 14496 is not stolen; you will be prompted for a passphrase). 14497 14498 So keep in mind no CA key creation or management 14499 (-sslGenCA and -sslGenCert) is needed for either of 14500 the above two common usage modes. 14501 14502 One might want to use -sslGenCA and -sslGenCert 14503 if you had a large number of VNC client and server 14504 workstations. That way the administrator could generate 14505 a single CA key with -sslGenCA and distribute its 14506 certificate part to all of the workstations. 14507 14508 Next, he could create signed VNC server keys 14509 (-sslGenCert server ...) for each workstation or user 14510 that then x11vnc would use to authenticate itself to 14511 any VNC client that has the CA cert. 14512 14513 Optionally, the admin could also make it so the 14514 VNC clients themselves are authenticated to x11vnc 14515 (-sslGenCert client ...) For this -sslverify would be 14516 pointed to the CA cert (and/or self-signed certs). 14517 14518 x11vnc will be able to use all of these cert and 14519 key files. On the VNC client side, they will need to 14520 be "imported" somehow. Web browsers have "Manage 14521 Certificates" actions as does the Java applet plugin 14522 Control Panel. stunnel can also use these files (see 14523 the ss_vncviewer example script in the FAQ and SSVNC.) 14524 14525 -sslCRL path Set the Certificate Revocation Lists (CRL) to "path". 14526 This setting applies for both -ssl and -stunnel modes. 14527 14528 If path is a file, the file contains one or more CRLs 14529 in PEM format. If path is a directory, it contains 14530 hash named files of CRLs in the usual OpenSSL manner. 14531 See the OpenSSL and stunnel(8) documentation for 14532 more info. 14533 14534 This option only applies if -sslverify has been 14535 supplied: it checks for revocation along the 14536 certificate chain used to verify the VNC client. 14537 The -sslCRL setting will be ignored when -sslverify is 14538 not specified. 14539 14540 Note that if a CRL's expiration date has passed, all 14541 SSL connections will fail regardless of if they are 14542 related to the subject of the CRL or not. 14543 14544 Only rarely will one's x11vnc -ssl infrastructure be so 14545 large that this option would be useful (since normally 14546 maintaining the contents of the -sslverify file or 14547 directory should be enough.) However, when using 14548 x11vnc with a Certificate Authority (see -sslGenCA) 14549 to authenticate Clients via SSL/TLS, the -sslCRL option 14550 can be useful to revoke users' certs whose private SSL 14551 keys were lost or stolen (e.g. laptop.) This way a new 14552 CA cert+key does not need to be created and new signed 14553 client keys generated and distributed to all users. 14554 14555 To create a CRL file with revoked certificates the 14556 commands 'openssl ca -revoke ...' and 'openssl ca 14557 -gencrl ...' are useful. (Run them in ~/.vnc/certs) 14558 14559 -sslGenCA [dir] Generate your own Certificate Authority private key, 14560 certificate, and other files in directory [dir]. 14561 x11vnc then exits. 14562 14563 If [dir] is not supplied, a -ssldir setting is used, 14564 or otherwise ~/.vnc/certs is used. 14565 14566 This command also creates directories where server and 14567 client certs and keys will be stored. The openssl(1) 14568 program must be installed on the system and available 14569 in PATH. 14570 14571 After the CA files and directories are created the 14572 x11vnc command exits; the VNC server is not run. 14573 14574 You will be prompted for information to put into the CA 14575 certificate. The info does not have to be accurate just 14576 as long as clients accept the cert for VNC connections. 14577 You will also need to supply a passphrase of at least 14578 4 characters for the CA private key. 14579 14580 Once you have generated the CA you can distribute 14581 its certificate part, [dir]/CA/cacert.pem, to other 14582 workstations where VNC viewers will be run. One will 14583 need to "import" this certificate in the applications, 14584 e.g. Web browser, Java applet plugin, stunnel, etc. 14585 Next, you can create and sign keys using the CA with 14586 the -sslGenCert option below. 14587 14588 Examples: 14589 x11vnc -sslGenCA 14590 x11vnc -sslGenCA ~/myCAdir 14591 x11vnc -ssldir ~/myCAdir -sslGenCA 14592 14593 (the last two lines are equivalent) 14594 14595 -sslGenCert type name Generate a VNC server or client certificate and private 14596 key pair signed by the CA created previously with 14597 -sslGenCA. The openssl(1) program must be installed 14598 on the system and available in PATH. 14599 14600 After the Certificate is generated x11vnc exits; the 14601 VNC server is not run. 14602 14603 The type of key to be generated is the string "type". 14604 It is either "server" (i.e. for use by x11vnc) or 14605 "client" (for a VNC viewer). Note that typically 14606 only "server" is used: the VNC clients authenticate 14607 themselves by a non-public-key method (e.g. VNC or 14608 unix password). "type" is required. 14609 14610 An arbitrary default name you want to associate with 14611 the key is supplied by the "name" string. You can 14612 change it at the various prompts when creating the key. 14613 "name" is optional. 14614 14615 If name is left blank for clients keys then "nobody" 14616 is used. If left blank for server keys, then the 14617 primary server key: "server.pem" is created (this 14618 is the saved one referenced by "-ssl SAVE" when the 14619 server is started) 14620 14621 If "name" begins with the string "self:" then 14622 a self-signed certificate is created instead of one 14623 signed by your CA key. 14624 14625 If "name" begins with the string "req:" then only a 14626 key (.key) and a certificate signing *request* (.req) 14627 are generated. You can then send the .req file to 14628 an external CA (even a professional one, e.g. Thawte) 14629 and then combine the .key and the received cert into 14630 the .pem file with the same basename. 14631 14632 The distinction between "server" and "client" is 14633 simply the choice of output filenames and sub-directory. 14634 This makes it so the -ssl SAVE-name option can easily 14635 pick up the x11vnc PEM file this option generates. 14636 And similarly makes it easy for the -sslverify option 14637 to pick up your client certs. 14638 14639 There is nothing special about the filename or directory 14640 location of either the "server" and "client" certs. 14641 You can rename the files or move them to wherever 14642 you like. 14643 14644 Precede this option with -ssldir [dir] to use a 14645 directory other than the default ~/.vnc/certs You will 14646 need to run -sslGenCA on that directory first before 14647 doing any -sslGenCert key creation. 14648 14649 Note you cannot recreate a cert with exactly the same 14650 distiguished name (DN) as an existing one. To do so, 14651 you will need to edit the [dir]/CA/index.txt file to 14652 delete the line. 14653 14654 Similar to -sslGenCA, you will be prompted to fill 14655 in some information that will be recorded in the 14656 certificate when it is created. 14657 14658 Tip: if you know the fully-qualified hostname other 14659 people will be connecting to, you can use that as the 14660 CommonName "CN" to avoid some applications (e.g. web 14661 browsers and java plugin) complaining that it does not 14662 match the hostname. 14663 14664 You will also need to supply the CA private key 14665 passphrase to unlock the private key created from 14666 -sslGenCA. This private key is used to sign the server 14667 or client certificate. 14668 14669 The "server" certs can be used by x11vnc directly by 14670 pointing to them via the -ssl [pem] option. The default 14671 file will be ~/.vnc/certs/server.pem. This one would 14672 be used by simply typing -ssl SAVE. The pem file 14673 contains both the certificate and the private key. 14674 server.crt file contains the cert only. 14675 14676 The "client" cert + private key file will need 14677 to be copied and imported into the VNC viewer 14678 side applications (Web browser, Java plugin, 14679 stunnel, etc.) Once that is done you can delete the 14680 "client" private key file on this machine since 14681 it is only needed on the VNC viewer side. The, 14682 e.g. ~/.vnc/certs/clients/<name>.pem contains both 14683 the cert and private key. The <name>.crt contains the 14684 certificate only. 14685 14686 NOTE: It is very important to know one should 14687 generate new keys with a passphrase. Otherwise if an 14688 untrusted user steals the key file he could use it to 14689 masquerade as the x11vnc server (or VNC viewer client). 14690 You will be prompted whether to encrypt the key with 14691 a passphrase or not. It is recommended that you do. 14692 One inconvenience to a passphrase is that it must 14693 be typed in EVERY time x11vnc or the client app is 14694 started up. 14695 14696 Examples: 14697 14698 x11vnc -sslGenCert server 14699 x11vnc -ssl SAVE -display :0 ... 14700 14701 and then on viewer using ss_vncviewer stunnel wrapper 14702 (see the FAQ): 14703 ss_vncviewer -verify ./cacert.crt hostname:0 14704 14705 (this assumes the cacert.crt cert from -sslGenCA 14706 was safely copied to the VNC viewer machine where 14707 ss_vncviewer is run) 14708 14709 Example using a name: 14710 14711 x11vnc -sslGenCert server charlie 14712 x11vnc -ssl SAVE-charlie -display :0 ... 14713 14714 Example for a client certificate (rarely used): 14715 14716 x11vnc -sslGenCert client roger 14717 scp ~/.vnc/certs/clients/roger.pem somehost:. 14718 rm ~/.vnc/certs/clients/roger.pem 14719 14720 x11vnc is then started with the option -sslverify 14721 ~/.vnc/certs/clients/roger.crt (or simply -sslverify 14722 roger), and on the viewer user on somehost could do 14723 for example: 14724 14725 ss_vncviewer -mycert ./roger.pem hostname:0 14726 14727 If you set the env. var REQ_ARGS='...' it will be 14728 passed to openssl req(1). A common use would be 14729 REQ_ARGS='-days 1095' to bump up the expiration date 14730 (3 years in this case). 14731 14732 -sslEncKey pem Utility to encrypt an existing PEM file with a 14733 passphrase you supply when prompted. For that key to be 14734 used (e.g. by x11vnc) the passphrase must be supplied 14735 each time. 14736 14737 The "SAVE" notation described under -ssl applies as 14738 well. (precede this option with -ssldir [dir] to refer 14739 a directory besides the default ~/.vnc/certs) 14740 14741 The openssl(1) program must be installed on the system 14742 and available in PATH. After the Key file is encrypted 14743 the x11vnc command exits; the VNC server is not run. 14744 14745 Examples: 14746 x11vnc -sslEncKey /path/to/foo.pem 14747 x11vnc -sslEncKey SAVE 14748 x11vnc -sslEncKey SAVE-charlie 14749 14750 -sslCertInfo pem Prints out information about an existing PEM file. 14751 In addition the public certificate is also printed. 14752 The openssl(1) program must be in PATH. Basically the 14753 command "openssl x509 -text" is run on the pem. 14754 14755 After the info is printed the x11vnc command exits; 14756 the VNC server is not run. 14757 14758 The "SAVE" notation described under -ssl applies 14759 as well. 14760 14761 Using "LIST" will give a list of all certs being 14762 managed (in the ~/.vnc/certs dir, use -ssldir to refer 14763 to another dir). "ALL" will print out the info for 14764 every managed key (this can be very long). Giving a 14765 client or server cert shortname will also try a lookup 14766 (e.g. -sslCertInfo charlie). Use "LISTL" or "LL" 14767 for a long (ls -l style) listing. 14768 14769 Using "HASHON" will create subdirs [dir]/HASH and 14770 [dir]/HASH with OpenSSL hash filenames (e.g. 0d5fbbf1.0) 14771 symlinks pointing up to the corresponding *.crt file. 14772 ([dir] is ~/.vnc/certs or one given by -ssldir.) 14773 This is a useful way for other OpenSSL applications 14774 (e.g. stunnel) to access all of the certs without 14775 having to concatenate them. x11vnc will not use them 14776 unless you specifically reference them. "HASHOFF" 14777 removes these HASH subdirs. 14778 14779 The LIST, LISTL, LL, ALL, HASHON, HASHOFF words can 14780 also be lowercase, e.g. "list". 14781 14782 -sslDelCert pem Prompts you to delete all .crt .pem .key .req files 14783 associated with [pem]. x11vnc then exits. "SAVE" 14784 and lookups as in -sslCertInfo apply as well. 14785 14786 -sslScripts Prints out both the 'genCA' and 'genCert' x11vnc 14787 openssl wrapper scripts for you to examine, modify, etc. 14788 The scripts are printed to stdout and then the x11vnc 14789 program exits. 14790 14791 14792 -stunnel [pem] Use the stunnel(8) (stunnel.mirt.net) to provide an 14793 encrypted SSL tunnel between viewers and x11vnc. 14794 14795 This external tunnel method was implemented prior to the 14796 integrated -ssl encryption described above. It still 14797 works well and avoids the requirement of linking with 14798 the OpenSSL libraries. This mode requires stunnel 14799 to be installed on the system and available via PATH 14800 (n.b. stunnel is often installed in sbin directories). 14801 Version 4.x of stunnel is assumed (but see -stunnel3 14802 below.) 14803 14804 [pem] is optional, use "-stunnel /path/to/stunnel.pem" 14805 to specify a PEM certificate file to pass to stunnel. 14806 See the -ssl option for more info on certificate files. 14807 14808 Whether or not your stunnel has its own certificate 14809 depends on your stunnel configuration; stunnel often 14810 generates one at install time. See your stunnel 14811 documentation for details. In any event, if you want to 14812 use this certificate you must supply the full path to it 14813 as [pem]. Note: the file may only be readable by root. 14814 14815 [pem] may also be the special strings "TMP", "SAVE", 14816 and "SAVE..." as described in the -ssl option. 14817 If [pem] is not supplied, "SAVE" is assumed. 14818 14819 Note that the VeNCrypt, ANONTLS, and "ANON" modes 14820 are not supported in -stunnel mode. 14821 14822 stunnel is started up as a child process of x11vnc and 14823 any SSL connections stunnel receives are decrypted and 14824 sent to x11vnc over a local socket. The strings 14825 "The SSL VNC desktop is ..." and "SSLPORT=..." 14826 are printed out at startup to indicate this. 14827 14828 The -localhost option is enforced by default to avoid 14829 people routing around the SSL channel. Use -env 14830 STUNNEL_DISABLE_LOCALHOST=1 to disable this security 14831 requirement. 14832 14833 Set -env STUNNEL_DEBUG=1 for more debugging printout. 14834 14835 Set -env STUNNEL_PROG=xxx to the full path of stunnel 14836 program you want to be used (e.g. /usr/bin/stunnel4). 14837 14838 Set -env STUNNEL_LISTEN=xxx to the address of the 14839 network interface to listen on (the default is to listen 14840 on all interfaces), e.g. STUNNEL_LISTEN=192.168.1.100. 14841 14842 A simple way to add IPv6 support is STUNNEL_LISTEN=:: 14843 14844 Your VNC viewer will also need to be able to connect 14845 via SSL. Unfortunately not too many do this. See the 14846 information about SSL viewers under the -ssl option. 14847 The x11vnc project's SSVNC is an option. 14848 14849 Also, in the x11vnc distribution, patched TightVNC 14850 and UltraVNC Java applet jar files are provided in 14851 the classes/ssl directory that do SSL connections. 14852 Enable serving them with the -http, -http_ssl, or 14853 -httpdir (see the option descriptions for more info.) 14854 14855 Note that for the Java viewer applet usage the 14856 "?PORT=xxxx" in the various URLs printed at startup 14857 will need to be supplied to the web browser to connect 14858 properly. 14859 14860 Currently the automatic "single port" HTTPS mode of 14861 -ssl is not fully supported in -stunnel mode. However, 14862 it can be emulated via: 14863 14864 % x11vnc -stunnel -http_ssl -http_oneport ... 14865 14866 In general, it is also not too difficult to set up 14867 an stunnel or other SSL tunnel on the viewer side. 14868 A simple example on Unix using stunnel 3.x is: 14869 14870 % stunnel -c -d localhost:5901 -r remotehost:5900 14871 % vncviewer localhost:1 14872 14873 For Windows, stunnel has been ported to it and there 14874 are probably other such tools available. See the FAQ 14875 and SSVNC for more examples. 14876 14877 -stunnel3 [pem] Use version 3.x stunnel command line syntax instead of 14878 version 4.x. The -http/-httpdir Java applet serving 14879 is currently not available in this mode. 14880 14881 -enc cipher:keyfile Use symmetric encryption with cipher "cipher" 14882 and secret key data in "keyfile". If keyfile is 14883 pw=<string> then "string" is used as the key data. 14884 14885 NOTE: It is recommended that you use SSL via the -ssl 14886 option instead of this option because SSL is well 14887 understood and takes great care to establish unique 14888 session keys and is more compatible with other software. 14889 Use this option if you do not want to deal with SSL 14890 certificates for authentication and do not want to 14891 use SSH but want some encryption for your VNC session. 14892 Or if you must interface with a symmetric key tunnel 14893 that you do not have control over. 14894 14895 Note that this mode will NOT work with the UltraVNC DSM 14896 plugins because they alter the RFB protocol in addition 14897 to tunnelling with the symmetric cipher (an unfortunate 14898 choice of implementation...) 14899 14900 cipher can be one of: arc4, aesv2, aes-cfb, blowfish, 14901 aes256, or 3des. See the OpenSSL documentation for 14902 more info. The keysize is 128 bits (except for aes256). 14903 Here is one way to make a keyfile with that many bits: 14904 14905 dd if=/dev/random of=./my.key bs=16 count=1 14906 14907 you will need to securely share this key with the other 14908 side of the VNC connection (See SSVNC for examples). 14909 14910 Example: -enc blowfish:./my.key 14911 Example: -enc blowfish:pw=swordfish 14912 14913 By default 16 bytes of random salt followed by 16 bytes 14914 of random initialization vector are sent at the very 14915 beginning of the stream. The other side must read these 14916 and initialize their cipher with them. These values 14917 make the session key unique (without them the security 14918 is minimal). Similarly, the other side must send us 14919 its random salt and IV with those same lengths. 14920 14921 The salt and key data are combined to create a session 14922 key using an md5 hash as described in EVP_BytesToKey(3). 14923 14924 The exact call is: EVP_BytesToKey(Cipher, EVP_md5(), 14925 salt, keydata, len, 1, keystr, NULL); where salt is 14926 the random data as described above, and keydata is the 14927 shared secret key data. keystr is the resulting session 14928 key. The cipher is then seeded with keystr and uses 14929 the random initialization vector as its first block. 14930 14931 To modify the amount of random salt and initialization 14932 vector use cipher@n,m where n is the salt length and 14933 m the initialization vector length. E.g. 14934 14935 -enc aes-cfb@8,16:./my.key 14936 14937 It is not a good idea to set either one to zero, 14938 although you may be forced to if the other side of the 14939 tunnel is not under your control. 14940 14941 To skip the salt and EVP_BytesToKey MD5 entirely (no 14942 hashing is done: the keydata is directly inserted into 14943 the cipher) specify "-1" for the salt, e.g. 14944 14945 -enc blowfish@-1,16:./my.key 14946 14947 The message digest can also be changed to something 14948 besides the default MD5. Use cipher@md+n,m where "md" 14949 can be one of sha, sha1, md5, or ripe. For example: 14950 14951 -enc arc4@sha+8,16:./my.key 14952 14953 The SSVNC vnc viewer project supplies a symmetric 14954 encryption tool named "ultravnc_dsm_helper" that can 14955 be used on the viewer side. For example: 14956 14957 ssvncviewer exec='ultravnc_dsm_helper arc4 my.key 0 h:p' 14958 14959 where h:p is the hostname and port of the x11vnc server. 14960 ultravnc_dsm_helper may also be used standalone to 14961 provide a symmetric encryption tunnel for any viewer 14962 or server (VNC or otherwise.) The cipher (1st arg) 14963 is basically the same syntax as we use above. 14964 14965 Also see the 'Non-Ultra DSM' SSVNC option for the 14966 'UltraVNC DSM Encryption Plugin' advanced option. 14967 14968 For both ways of using the viewer, you can specify the 14969 salt,ivec sizes (in GUI or, e.g. arc4@8,16). 14970 14971 -https [port] Use a special, separate HTTPS port (-ssl and 14972 -stunnel modes only) for HTTPS Java viewer applet 14973 downloading. I.e. not 5900 and not 5800 (the defaults.) 14974 14975 BACKGROUND: In -ssl mode, it turns out you can use the 14976 single VNC port (e.g. 5900) for both VNC and HTTPS 14977 connections. (HTTPS is used to retrieve a SSL-aware 14978 VncViewer.jar applet that is provided with x11vnc). 14979 Since both use SSL the implementation was extended to 14980 detect if HTTP traffic (i.e. GET) is taking place and 14981 handle it accordingly. The URL would be, e.g.: 14982 14983 https://mymachine.org:5900/ 14984 14985 This is convenient for firewalls, etc, because only one 14986 port needs to be allowed in. However, this heuristic 14987 adds a few seconds delay to each connection and can be 14988 unreliable (especially if the user takes much time to 14989 ponder the Certificate dialogs in his browser, Java VM, 14990 or VNC Viewer applet. That's right 3 separate "Are 14991 you sure you want to connect?" dialogs!) 14992 14993 END OF BACKGROUND. 14994 14995 USAGE: So use the -https option to provide a separate, 14996 more reliable HTTPS port that x11vnc will listen on. If 14997 [port] is not provided (or is 0), one is autoselected. 14998 The URL to use is printed out at startup. 14999 15000 The SSL Java applet directory is specified via the 15001 -httpdir option. If not supplied, -https will try 15002 to guess the directory as though the -http option 15003 was supplied. 15004 15005 -httpsredir [port] In -ssl mode with the Java applet retrieved via HTTPS, 15006 when the HTML file containing applet parameters 15007 ('index.vnc' or 'proxy.vnc') is sent do NOT set the 15008 applet PORT parameter to the actual VNC port but set it 15009 to "port" instead. If "port" is not supplied, then 15010 the port number is guessed from the Host: HTTP header. 15011 15012 This is useful when an incoming TCP connection 15013 redirection is performed by a router/gateway/firewall 15014 from one port to an internal machine where x11vnc is 15015 listening on a different port. The Java applet needs to 15016 connect to the firewall/router port, not the VNC port 15017 on the internal workstation. For example, one could 15018 redir from mygateway.com:443 to workstation:5900. 15019 15020 This spares the user from having to type in 15021 https://mygateway.com/?PORT=443 into their web 15022 browser. Note that port 443 is the default https port; 15023 other ports must be explicitly indicated, for example: 15024 https://mygateway.com:8000/?PORT=8000. To avoid having 15025 to include the PORT= in the browser URL, simply supply 15026 "-httpsredir" to x11vnc. 15027 15028 This option does not work in -stunnel mode. 15029 15030 More tricks: set the env var X11VNC_EXTRA_HTTPS_PARAMS 15031 to be extra URL parameters to use. This way you do 15032 not need to specify extra PARAMS in the index.vnc file. 15033 E.g. x11vnc -env X11VNC_EXTRA_HTTPS_PARAMS='?GET=1' ... 15034 15035 If you do not want to expose the non-SSL HTTP port to 15036 the network (i.e. you just want the single VNC/HTTPS 15037 port, e.g. 5900, open for connections) then specify the 15038 option -env X11VNC_HTTP_LISTEN_LOCALHOST=1 This way 15039 the connection to the LibVNCServer httpd server will 15040 only be available on localhost (note that in -ssl mode, 15041 HTTPS requests are redirected from SSL to the non-SSL 15042 LibVNCServer HTTP server.) 15043 15044 -http_oneport For UN-encrypted connections mode (i.e. no -ssl, 15045 -stunnel, or -enc options), allow the Java VNC Viewer 15046 applet to be downloaded thru the VNC port via HTTP. 15047 15048 That is to say, you can use a single port for Java 15049 applet viewer connections by using a URL in your web 15050 browser like this, for example: 15051 15052 http://hostname:5900 15053 15054 The regular, two-port mode, URL http://hostname:5800 15055 will continue to work as well. 15056 15057 As mentioned above, this mode will NOT work with 15058 the -ssl, -stunnel, or -enc encryption options. 15059 Note that is it equivalent to '-enc none' (i.e. it 15060 uses the same detection mechanism as for HTTPS, but 15061 with no encryption.) 15062 15063 HTTPS single-port is on by default in -ssl encrypted 15064 mode (and -enc too), so you only need -http_oneport 15065 when doing non-SSL encrypted connections. 15066 15067 This mode could also be useful for SSH tunnels since 15068 it means only one port needs to be redirected. 15069 15070 The -httpsredir option may also be useful for this 15071 mode when using an SSH tunnel as well as for router 15072 port redirections. 15073 15074 Note that the -env X11VNC_HTTP_LISTEN_LOCALHOST=1 15075 option described above under -httpsredir applies for 15076 the LibVNCServer httpd server in all cases (ssl or not.) 15077 15078 -ssh user@host:disp Create a remote listening port on machine "host" 15079 via a SSH tunnel using the -R rport:localhost:lport 15080 method. lport will be the local x11vnc listening port, 15081 so a connection to rport (5900+disp) on "host" 15082 will reach x11vnc. E.g. fred (a] snoopy.com:0 15083 15084 This could be useful if a firewall/router prevents 15085 incoming connections to the x11vnc machine, but 15086 the ssh machine "host" can be reached by the VNC 15087 viewer. "user@" is not needed unless the remote unix 15088 username differs from the current one. 15089 15090 By default the remote sshd is usually configured to 15091 listen only on localhost for rport, so the viewer may 15092 need to ssh -L redir to "host" as well (See SSVNC to 15093 automate this). The sshd setting GatewayPorts enables 15094 listening on all interfaces for rport; viewers can 15095 reach it more easily. 15096 15097 "disp" is the VNC display for the remote SSH side, 15098 e.g. 0 corresponds to port 5900, etc. If disp is 15099 greater than 200 the value is used as the port. Use a 15100 negative value to force a low port, e.g. host:-80 will 15101 use port 80. 15102 15103 If ssh-agent is not active, then the ssh password needs 15104 to be entered in the terminal where x11vnc is running. 15105 15106 By default the remote ssh will issue a 'sleep 300' to 15107 wait for the incoming connection for 5 mins. To modify 15108 this use user@host:disp+secs. 15109 15110 If the remote SSH server is on a non-standard port 15111 (i.e. not 22) use user@host:port:disp+secs. 15112 15113 Note that the ssh process MAY NOT be killed when 15114 x11vnc exits. It tries by looking at ps(1) output. 15115 15116 -usepw If no other password method was supplied on the command 15117 line, first look for ~/.vnc/passwd and if found use it 15118 with -rfbauth; next, look for ~/.vnc/passwdfile and 15119 use it with -passwdfile; otherwise, prompt the user 15120 for a password to create ~/.vnc/passwd and use it with 15121 the -rfbauth option. If none of these succeed x11vnc 15122 exits immediately. 15123 15124 -storepasswd pass file Store password "pass" as the VNC password in the 15125 file "file". Once the password is stored the 15126 program exits. Use the password via "-rfbauth file" 15127 15128 If called with no arguments, "x11vnc -storepasswd", 15129 the user is prompted for a password and it is stored 15130 in the file ~/.vnc/passwd. Called with one argument, 15131 that will be the file to store the prompted password in. 15132 15133 -nopw Disable the big warning message when you use x11vnc 15134 without some sort of password. 15135 15136 -accept string Run a command (possibly to prompt the user at the 15137 X11 display) to decide whether an incoming client 15138 should be allowed to connect or not. "string" is 15139 an external command run via system(3) or some special 15140 cases described below. Be sure to quote "string" 15141 if it contains spaces, shell characters, etc. If the 15142 external command returns 0 the client is accepted, 15143 otherwise the client is rejected. See below for an 15144 extension to accept a client view-only. 15145 15146 If x11vnc is running as root (say from inetd(8) or from 15147 display managers xdm(1), gdm(1), etc), think about the 15148 security implications carefully before supplying this 15149 option (likewise for the -gone option). 15150 15151 Environment: The RFB_CLIENT_IP environment variable will 15152 be set to the incoming client IP number and the port 15153 in RFB_CLIENT_PORT (or -1 if unavailable). Similarly, 15154 RFB_SERVER_IP and RFB_SERVER_PORT (the x11vnc side 15155 of the connection), are set to allow identification 15156 of the tcp virtual circuit. The x11vnc process 15157 id will be in RFB_X11VNC_PID, a client id number in 15158 RFB_CLIENT_ID, and the number of other connected clients 15159 in RFB_CLIENT_COUNT. RFB_MODE will be "accept". 15160 RFB_STATE will be PROTOCOL_VERSION, SECURITY_TYPE, 15161 AUTHENTICATION, INITIALISATION, NORMAL, or UNKNOWN 15162 indicating up to which state the client has achieved. 15163 RFB_LOGIN_VIEWONLY will be 0, 1, or -1 (unknown). 15164 RFB_USERNAME, RFB_LOGIN_TIME, and RFB_CURRENT_TIME may 15165 also be set. 15166 15167 If "string" is "popup" then a builtin popup window 15168 is used. The popup will time out after 120 seconds, 15169 use "popup:N" to modify the timeout to N seconds 15170 (use 0 for no timeout). 15171 15172 In the case of "popup" and when the -unixpw option 15173 is specified, then a *second* window will be popped 15174 up after the user successfully logs in via his UNIX 15175 password. This time the user will be identified as 15176 UNIX:username@hostname, the "UNIX:" prefix indicates 15177 which user the viewer logged as via -unixpw. The first 15178 popup is only for whether to allow him to even *try* 15179 to login via unix password. 15180 15181 If "string" is "xmessage" then an xmessage(1) 15182 invocation is used for the command. xmessage must be 15183 installed on the machine for this to work. 15184 15185 Both "popup" and "xmessage" will present an option 15186 for accepting the client "View-Only" (the client 15187 can only watch). This option will not be presented if 15188 -viewonly has been specified, in which case the entire 15189 display is view only. 15190 15191 If the user supplied command is prefixed with something 15192 like "yes:0,no:*,view:3 mycommand ..." then this 15193 associates the numerical command return code with 15194 the actions: accept, reject, and accept-view-only, 15195 respectively. Use "*" instead of a number to indicate 15196 the default action (in case the command returns an 15197 unexpected value). E.g. "no:*" is a good choice. 15198 15199 Note that x11vnc blocks while the external command 15200 or popup is running (other clients may see no updates 15201 during this period). So a person sitting a the physical 15202 display is needed to respond to an popup prompt. (use 15203 a 2nd x11vnc if you lock yourself out). 15204 15205 More -accept tricks: use "popupmouse" to only allow 15206 mouse clicks in the builtin popup to be recognized. 15207 Similarly use "popupkey" to only recognize 15208 keystroke responses. These are to help avoid the 15209 user accidentally accepting a client by typing or 15210 clicking. All 3 of the popup keywords can be followed 15211 by +N+M to supply a position for the popup window. 15212 The default is to center the popup window. 15213 -afteraccept string As -accept, except to run a user supplied command after 15214 a client has been accepted and authenticated. RFB_MODE 15215 will be set to "afteraccept" and the other RFB_* 15216 variables are as in -accept. Unlike -accept, the 15217 command return code is not interpreted by x11vnc. 15218 Example: -afteraccept 'killall xlock &' 15219 -gone string As -accept, except to run a user supplied command when 15220 a client goes away (disconnects). RFB_MODE will be 15221 set to "gone" and the other RFB_* variables are as 15222 in -accept. The "popup" actions apply as well. 15223 Unlike -accept, the command return code is not 15224 interpreted by x11vnc. Example: -gone 'xlock &' 15225 15226 -users list If x11vnc is started as root (say from inetd(8) or from 15227 display managers xdm(1), gdm(1), etc), then as soon 15228 as possible after connections to the X display are 15229 established try to switch to one of the users in the 15230 comma separated "list". If x11vnc is not running as 15231 root this option is ignored. 15232 15233 Why use this option? In general it is not needed since 15234 x11vnc is already connected to the X display and can 15235 perform its primary functions. The option was added 15236 to make some of the *external* utility commands x11vnc 15237 occasionally runs work properly. In particular under 15238 GNOME and KDE to implement the "-solid color" feature 15239 external commands (gconftool-2 and dcop) unfortunately 15240 must be run as the user owning the desktop session. 15241 Since this option switches userid it also affects the 15242 userid used to run the processes for the -accept and 15243 -gone options. It also affects the ability to read 15244 files for options such as -connect, -allow, and -remap 15245 and also the ultra and tight filetransfer feature if 15246 enabled. Note that the -connect file is also sometimes 15247 written to. 15248 15249 So be careful with this option since in some situations 15250 its use can decrease security. 15251 15252 In general the switch to a user will only take place 15253 if the display can still be successfully opened as that 15254 user (this is primarily to try to guess the actual owner 15255 of the session). Example: "-users fred,wilma,betty". 15256 Note that a malicious local user "barney" by 15257 quickly using "xhost +" when logging in may possibly 15258 get the x11vnc process to switch to user "fred". 15259 What happens next? 15260 15261 Under display managers it may be a long time before 15262 the switch succeeds (i.e. a user logs in). To instead 15263 make it switch immediately regardless if the display 15264 can be reopened prefix the username with the "+" 15265 character. E.g. "-users +bob" or "-users +nobody". 15266 15267 The latter (i.e. switching immediately to user 15268 "nobody") is the only obvious use of the -users option 15269 that increases security. 15270 15271 Use the following notation to associate a group with 15272 a user: user1.group1,user2.group2,... Note that 15273 initgroups(2) will still be called first to try to 15274 switch to ALL of a user's groups (primary and additional 15275 groups). Only if that fails or it is not available 15276 then the single group specified as above (or the user's 15277 primary group if not specified) is switched to with 15278 setgid(2). Use -env X11VNC_SINGLE_GROUP=1 to prevent 15279 trying initgroups(2) and only switch to the single 15280 group. This sort of setting is only really needed to 15281 make the ultra or tight filetransfer permissions work 15282 properly. This format applies to any comma separated lis 15283 t 15284 of users, even the special "=" modes described below. 15285 15286 In -unixpw mode, if "-users unixpw=" is supplied 15287 then after a user authenticates himself via the 15288 -unixpw mechanism, x11vnc will try to switch to that 15289 user as though "-users +username" had been supplied. 15290 If you want to limit which users this will be done for, 15291 provide them as a comma separated list after "unixpw=" 15292 Groups can also be specified as described above. 15293 15294 Similarly, in -ssl mode, if "-users sslpeer=" is 15295 supplied then after an SSL client authenticates with his 15296 cert (the -sslverify option is required for this) x11vnc 15297 will extract a UNIX username from the "emailAddress" 15298 field (username (a] hostname.com) of the "Subject" of the 15299 x509 SSL cert and then try to switch to that user as 15300 though "-users +username" had been supplied. If you 15301 want to limit which users this will be done for, provide 15302 them as a comma separated list after "sslpeer=". 15303 Set the env. var X11VNC_SSLPEER_CN to use the Common 15304 Name (normally a hostname) instead of the Email field. 15305 15306 NOTE: for sslpeer= mode the x11vnc administrator must 15307 take care that any client certs he adds to -sslverify 15308 have the intended UNIX username in the "emailAddress" 15309 field of the cert. Otherwise a user may be able to 15310 log in as another. This command can be of use in 15311 checking: "openssl x509 -text -in file.crt", see the 15312 "Subject:" line. Also, along with the normal RFB_* 15313 env. vars. (see -accept) passed to external cmd= 15314 commands, RFB_SSL_CLIENT_CERT will be set to the 15315 client's x509 certificate string. 15316 15317 The sslpeer= mode can aid finding X sessions via the 15318 FINDDISPLAY and FINDCREATEDISPLAY mechanisms. 15319 15320 To immediately switch to a user *before* connections 15321 to the X display are made or any files opened use the 15322 "=" character: "-users =bob". That user needs to 15323 be able to open the X display and any files of course. 15324 15325 The special user "guess=" means to examine the utmpx 15326 database (see who(1)) looking for a user attached to 15327 the display number (from DISPLAY or -display option) 15328 and try him/her. To limit the list of guesses, use: 15329 "-users guess=bob,betty". 15330 15331 Even more sinister is the special user "lurk=" 15332 that means to try to guess the DISPLAY from the utmpx 15333 login database as well. So it "lurks" waiting for 15334 anyone to log into an X session and then connects to it. 15335 Specify a list of users after the = to limit which users 15336 will be tried. To enable a different searching mode, if 15337 the first user in the list is something like ":0" or 15338 ":0-2" that indicates a range of DISPLAY numbers that 15339 will be tried (regardless of whether they are in the 15340 utmpx database) for all users that are logged in. Also 15341 see the "-display WAIT:..." functionality. Examples: 15342 "-users lurk=" and also "-users lurk=:0-1,bob,mary" 15343 15344 Be especially careful using the "guess=" and "lurk=" 15345 modes. They are not recommended for use on machines 15346 with untrustworthy local users. 15347 15348 -noshm Do not use the MIT-SHM extension for the polling. 15349 Remote displays can be polled this way: be careful this 15350 can use large amounts of network bandwidth. This is 15351 also of use if the local machine has a limited number 15352 of shm segments and -onetile is not sufficient. 15353 -flipbyteorder Sometimes needed if remotely polled host has different 15354 endianness. Ignored unless -noshm is set. 15355 -onetile Do not use the new copy_tiles() framebuffer mechanism, 15356 just use 1 shm tile for polling. Limits shm segments 15357 used to 3. 15358 15359 To disable any automatic shm reduction set the 15360 env. var. X11VNC_NO_LIMIT_SHM. 15361 15362 -solid [color] To improve performance, when VNC clients are connected 15363 try to change the desktop background to a solid color. 15364 The [color] is optional: the default color is "cyan4". 15365 For a different one specify the X color (rgb.txt name, 15366 e.g. "darkblue" or numerical "#RRGGBB"). 15367 15368 Currently this option only works on GNOME, KDE, CDE, 15369 XFCE, and classic X (i.e. with the background image 15370 on the root window). The "gconftool-2", "dcop" 15371 and "xfconf-query" external commands are run for 15372 GNOME, KDE, and XFCE respectively. This also works 15373 on native MacOSX. (There is no color selection for 15374 MacOSX or XFCE.) Other desktops won't work, (send 15375 us the corresponding commands if you find them). 15376 If x11vnc is running as root (inetd(8) or gdm(1)), 15377 the -users option may be needed for GNOME, KDE, XFCE. 15378 If x11vnc guesses your desktop incorrectly, you can 15379 force it by prefixing color with "gnome:", "kde:", 15380 "cde:", "xfce:", or "root:". 15381 15382 Update: -solid no longer works on KDE4. 15383 15384 This mode works in a limited way on the Mac OS X Console 15385 with one color ('kelp') using the screensaver writing 15386 to the background. Look in "~/Library/Screen Savers" 15387 for VncSolidColor.png to change the color. 15388 15389 -blackout string Black out rectangles on the screen. "string" is a 15390 comma separated list of WxH+X+Y type geometries for 15391 each rectangle. If one of the items on the list is the 15392 string "noptr" the mouse pointer will not be allowed 15393 to go into a blacked out region. 15394 -xinerama If your screen is composed of multiple monitors 15395 -noxinerama glued together via XINERAMA, and that screen is 15396 not a rectangle this option will try to guess the 15397 areas to black out (if your system has libXinerama). 15398 default: -xinerama 15399 15400 In general, we have noticed on XINERAMA displays you may 15401 need to use the "-xwarppointer" option if the mouse 15402 pointer misbehaves and it is enabled by default. Use 15403 "-noxwarppointer" if you do not want this. 15404 15405 -xtrap Use the DEC-XTRAP extension for keystroke and mouse 15406 input insertion. For use on legacy systems, e.g. X11R5, 15407 running an incomplete or missing XTEST extension. 15408 By default DEC-XTRAP will be used if XTEST server grab 15409 control is missing, use -xtrap to do the keystroke and 15410 mouse insertion via DEC-XTRAP as well. 15411 15412 -xrandr [mode] If the display supports the XRANDR (X Resize, Rotate 15413 and Reflection) extension, and you expect XRANDR events 15414 to occur to the display while x11vnc is running, this 15415 options indicates x11vnc should try to respond to 15416 them (as opposed to simply crashing by assuming the 15417 old screen size). See the xrandr(1) manpage and run 15418 'xrandr -q' for more info. [mode] is optional and 15419 described below. 15420 15421 Since watching for XRANDR events and trapping errors 15422 increases polling overhead, only use this option if 15423 XRANDR changes are expected. For example on a rotatable 15424 screen PDA or laptop, or using a XRANDR-aware Desktop 15425 where you resize often. It is best to be viewing with a 15426 vncviewer that supports the NewFBSize encoding, since it 15427 knows how to react to screen size changes. Otherwise, 15428 LibVNCServer tries to do so something reasonable for 15429 viewers that cannot do this (portions of the screen 15430 may be clipped, unused, etc). 15431 15432 Note: the default now is to check for XRANDR events, but 15433 do not trap every X call that may fail due to resize. 15434 If a resize event is received, the full -xrandr mode 15435 is enabled. To disable even checking for events supply: 15436 -noxrandr. 15437 15438 "mode" defaults to "resize", which means create a 15439 new, resized, framebuffer and hope all viewers can cope 15440 with the change. "newfbsize" means first disconnect 15441 all viewers that do not support the NewFBSize VNC 15442 encoding, and then resize the framebuffer. "exit" 15443 means disconnect all viewer clients, and then terminate 15444 x11vnc. 15445 15446 -rotate string Rotate and/or flip the framebuffer view exported by VNC. 15447 This transformation is independent of XRANDR and is 15448 done in software in main memory and so may be slower. 15449 This mode could be useful on a handheld with portrait or 15450 landscape modes that do not correspond to the scanline 15451 order of the actual framebuffer. "string" can be: 15452 15453 x flip along x-axis 15454 y flip along y-axis 15455 xy flip along x- and y-axes 15456 +90 rotate 90 degrees clockwise 15457 -90 rotate 90 degrees counter-clockwise 15458 +90x rotate 90 degrees CW, then flip along x 15459 +90y rotate 90 degrees CW, then flip along y 15460 15461 these give all possible rotations and reflections. 15462 15463 Aliases: same as xy: yx, +180, -180, 180 15464 same as -90: +270, 270 15465 same as +90: 90, (ditto for 90x, 90y) 15466 15467 Like -scale, this transformation is applied at the very 15468 end of any chain of framebuffer transformations and so 15469 any options with geometries, e.g. -blackout, -clip, etc. 15470 are relative to the original X (or -rawfb) framebuffer, 15471 not the final one sent to VNC viewers. 15472 15473 If you do not want the cursor shape to be rotated 15474 prefix "string" with "nc:", e.g. "nc:+90", 15475 "nc:xy", etc. 15476 15477 -padgeom WxH Whenever a new vncviewer connects, the framebuffer is 15478 replaced with a fake, solid black one of geometry WxH. 15479 Shortly afterwards the framebuffer is replaced with the 15480 real one. This is intended for use with vncviewers 15481 that do not support NewFBSize and one wants to make 15482 sure the initial viewer geometry will be big enough 15483 to handle all subsequent resizes (e.g. under -xrandr, 15484 -remote id:windowid, rescaling, etc.) 15485 15486 In -unixpw mode this sets the size of the login screen. 15487 Use "once:WxH" it ignore padgeom after the login 15488 screen is set up. 15489 15490 -o logfile Write stderr messages to file "logfile" instead of to 15491 the terminal. Same as "-logfile file". To append 15492 to the file use "-oa file" or "-logappend file". 15493 If "logfile" contains the string "%VNCDISPLAY" 15494 it is expanded to the vnc display (the name may need 15495 to be guessed at.) "%HOME" works too. 15496 15497 -flag file Write the "PORT=NNNN" (e.g. PORT=5900) string to 15498 "file" in addition to stdout. This option could be 15499 useful by wrapper script to detect when x11vnc is ready. 15500 15501 -rmflag file Remove "file" at exit to signal when x11vnc is done. 15502 The file is created at startup if it does not already 15503 exist or if "file" is prefixed with "create:". 15504 If the file is created, the x11vnc PID is placed in 15505 the file. Otherwise the files contents is not changed. 15506 Use prefix "nocreate:" to prevent creation. 15507 15508 -rc filename Use "filename" instead of $HOME/.x11vncrc for rc file. 15509 -norc Do not process any .x11vncrc file for options. 15510 15511 -env VAR=VALUE Set the environment variable 'VAR' to value 'VALUE' 15512 at x11vnc startup. This is a convenience utility to 15513 avoid shell script wrappers, etc. to set the env. var. 15514 You may specify as many of these as needed on the 15515 command line. 15516 -prog /path/to/x11vnc Set the full path to the x11vnc program for cases when 15517 it cannot be determined from argv[0] (e.g. tcpd/inetd) 15518 15519 -h, -help Print this help text. 15520 -?, -opts Only list the x11vnc options. 15521 -V, -version Print program version and last modification date. 15522 -license Print out license information. Same as -copying and 15523 -warranty. 15524 15525 -dbg Instead of exiting after cleaning up, run a simple 15526 "debug crash shell" when fatal errors are trapped. 15527 15528 -q, -quiet Be quiet by printing less informational output to 15529 stderr. (use -noquiet to undo an earlier -quiet.) 15530 15531 The -quiet option does not eliminate all informational 15532 output, it only reduces it. It is ignored in most 15533 auxiliary usage modes, e.g. -storepasswd. To eliminate 15534 all output use: 2>/dev/null 1>&2, etc. 15535 15536 -v, -verbose Print out more information to stderr. 15537 15538 -bg Go into the background after screen setup. Messages to 15539 stderr are lost unless -o logfile is used. Something 15540 like this could be useful in a script: 15541 port=`ssh -t $host "x11vnc -display :0 -bg" | grep PORT 15542 ` 15543 port=`echo "$port" | sed -e 's/PORT=//'` 15544 port=`expr $port - 5900` 15545 vncviewer $host:$port 15546 15547 -modtweak Option -modtweak automatically tries to adjust the AltGr 15548 -nomodtweak and Shift modifiers for differing language keyboards 15549 between client and host. Otherwise, only a single key 15550 press/release of a Keycode is simulated (i.e. ignoring 15551 the state of the modifiers: this usually works for 15552 identical keyboards). Also useful in resolving cases 15553 where a Keysym is bound to multiple keys (e.g. "<" + ">" 15554 and "," + "<" keys). Default: -modtweak 15555 15556 If you are having trouble with with keys and -xkb or 15557 -noxkb, and similar things don't help, try -nomodtweak. 15558 15559 On some HP-UX systems it is been noted that they have 15560 an odd keymapping where a single keycode will have a 15561 keysym, e.g. "#", up to three times. You can check 15562 via "xmodmap -pk" or the -dk option. The failure 15563 is when you try to type "#" it yields "3". If you 15564 see this problem try setting the environment variable 15565 MODTWEAK_LOWEST=1 to see if it helps. 15566 15567 -xkb When in modtweak mode, use the XKEYBOARD extension (if 15568 -noxkb the X display supports it) to do the modifier tweaking. 15569 This is powerful and should be tried if there are still 15570 keymapping problems when using -modtweak by itself. 15571 The default is to check whether some common keysyms, 15572 e.g. !, @, [, are only accessible via -xkb mode and if 15573 so then automatically enable the mode. To disable this 15574 automatic detection use -noxkb. 15575 15576 When -xkb mode is active you can set these env. vars. 15577 They apply only when there is ambiguity as to which 15578 key to choose (i.e the mapping is not one-to-one). 15579 NOKEYHINTS=1: for up ascii keystrokes do not use score 15580 hints saved when the key was pressed down. NOANYDOWN=1: 15581 for up keystrokes do not resort to searching through 15582 keys that are currently pressed down. KEYSDOWN=N: 15583 remember the last N keys press down for tie-breaking 15584 when an up keystroke comes in. 15585 15586 -capslock When in -modtweak (the default) or -xkb mode, 15587 if a keysym in the range A-Z comes in check the X 15588 server to see if the Caps_Lock is set. If it is do 15589 not artificially press Shift to generate the keysym. 15590 This will enable the CapsLock key to behave correctly 15591 in some circumstances: namely *both* the VNC viewer 15592 machine and the x11vnc X server are in the CapsLock 15593 on state. If one side has CapsLock on and the other 15594 off and the keyboard is not behaving as you think it 15595 should you should correct the CapsLock states (hint: 15596 pressing CapsLock inside and outside of the viewer can 15597 help toggle them both to the correct state). However, 15598 for best results do not use this option, but rather 15599 *only* enable CapsLock on the VNC viewer side (i.e. by 15600 pressing CapsLock outside of the viewer window, also 15601 -skip_lockkeys below). Also try -nomodtweak for a 15602 possible workaround. 15603 15604 -skip_lockkeys Have x11vnc ignore all Caps_Lock, Shift_Lock, Num_Lock, 15605 -noskip_lockkeys Scroll_Lock keysyms received from viewers. The idea is 15606 you press Caps_Lock on the VNC Viewer side but that does 15607 not change the lock state in the x11vnc-side X server. 15608 Nevertheless your capitalized letters come in over 15609 the wire and are applied correctly to the x11vnc-side 15610 X server. Note this mode probably won't do what you 15611 want in -nomodtweak mode. Also, a kludge for KP_n 15612 digits is always done in this mode: they are mapped to 15613 regular digit keysyms. See also -capslock above. 15614 The default is -noskip_lockkeys. 15615 15616 -skip_keycodes string Ignore the comma separated list of decimal keycodes. 15617 Perhaps these are keycodes not on your keyboard but 15618 your X server thinks exist. Currently only applies 15619 to -xkb mode. Use this option to help x11vnc in the 15620 reverse problem it tries to solve: Keysym -> Keycode(s) 15621 when ambiguities exist (more than one Keycode per 15622 Keysym). Run 'xmodmap -pk' to see your keymapping. 15623 Example: "-skip_keycodes 94,114" 15624 -sloppy_keys Experimental option that tries to correct some 15625 "sloppy" key behavior. E.g. if at the viewer you 15626 press Shift+Key but then release the Shift before 15627 Key that could give rise to extra unwanted characters 15628 (usually only between keyboards of different languages). 15629 Only use this option if you observe problems with 15630 some keystrokes. 15631 -skip_dups Some VNC viewers send impossible repeated key events, 15632 -noskip_dups e.g. key-down, key-down, key-up, key-up all for the same 15633 key, or 20 downs in a row for the same modifier key! 15634 Setting -skip_dups means to skip these duplicates and 15635 just process the first event. Note: some VNC viewers 15636 assume they can send down's without the corresponding 15637 up's and so you should not set this option for 15638 these viewers (symptom: some keys do not autorepeat) 15639 Default: -noskip_dups 15640 -add_keysyms If a Keysym is received from a VNC viewer and that 15641 -noadd_keysyms Keysym does not exist in the X server, then add the 15642 Keysym to the X server's keyboard mapping on an unused 15643 key. Added Keysyms will be removed periodically and 15644 also when x11vnc exits. Default: -add_keysyms 15645 -clear_mods At startup and exit clear the modifier keys by sending 15646 KeyRelease for each one. The Lock modifiers are skipped. 15647 Used to clear the state if the display was accidentally 15648 left with any pressed down. 15649 -clear_keys As -clear_mods, except try to release ANY pressed key. 15650 Note that this option and -clear_mods can interfere 15651 with a person typing at the physical keyboard. 15652 -clear_all As -clear_keys, except try to release any CapsLock, 15653 NumLock, etc. locks as well. 15654 15655 -remap string Read Keysym remappings from file named "string". 15656 Format is one pair of Keysyms per line (can be name 15657 or hex value) separated by a space. If no file named 15658 "string" exists, it is instead interpreted as this 15659 form: key1-key2,key3-key4,... See <X11/keysymdef.h> 15660 header file for a list of Keysym names, or use xev(1). 15661 15662 To map a key to a button click, use the fake Keysyms 15663 "Button1", ..., etc. E.g: "-remap Super_R-Button2" 15664 (useful for pasting on a laptop) 15665 15666 I use these if the machine I am viewing from does not 15667 have a scrollwheel or I don't like using the one it has: 15668 15669 -remap Super_R-Button4,Menu-Button5 15670 -remap KP_Add-Button4,KP_Enter-Button5 15671 15672 the former would be used on a PC, the latter on a 15673 MacBook. This way those little used keys can be used 15674 to generate bigger hops than the Up and Down arrows 15675 provide. One can scroll through text or web pages more 15676 quickly this way (especially if x11vnc scroll detection 15677 is active.) 15678 15679 Use Button44, Button12, etc. for multiple clicks. 15680 15681 To disable a keysym (i.e. make it so it will not be 15682 injected), remap it to "NoSymbol" or "None". 15683 15684 Dead keys: "dead" (or silent, mute) keys are keys that 15685 do not produce a character but must be followed by a 2nd 15686 keystroke. This is often used for accenting characters, 15687 e.g. to put "`" on top of "a" by pressing the dead 15688 key and then "a". Note that this interpretation 15689 is not part of core X11, it is up to the toolkit or 15690 application to decide how to react to the sequence. 15691 The X11 names for these keysyms are "dead_grave", 15692 "dead_acute", etc. However some VNC viewers send the 15693 keysyms "grave", "acute" instead thereby disabling 15694 the accenting. To work around this -remap can be used. 15695 For example "-remap grave-dead_grave,acute-dead_acute" 15696 As a convenience, "-remap DEAD" applies these remaps: 15697 15698 g grave-dead_grave 15699 a acute-dead_acute 15700 c asciicircum-dead_circumflex 15701 t asciitilde-dead_tilde 15702 m macron-dead_macron 15703 b breve-dead_breve 15704 D abovedot-dead_abovedot 15705 d diaeresis-dead_diaeresis 15706 o degree-dead_abovering 15707 A doubleacute-dead_doubleacute 15708 r caron-dead_caron 15709 e cedilla-dead_cedilla 15710 15711 If you just want a subset use the first letter 15712 label, e.g. "-remap DEAD=ga" to get the first two. 15713 Additional remaps may also be supplied via commas, 15714 e.g. "-remap DEAD=ga,Super_R-Button2". Finally, 15715 "DEAD=missing" means to apply all of the above as 15716 long as the left hand member is not already in the 15717 X11 keymap. 15718 15719 -norepeat Option -norepeat disables X server key auto repeat when 15720 -repeat VNC clients are connected and VNC keyboard input is 15721 not idle for more than 5 minutes. This works around a 15722 repeating keystrokes bug (triggered by long processing 15723 delays between key down and key up client events: 15724 either from large screen changes or high latency). 15725 Default: -norepeat 15726 15727 You can set the env. var. X11VNC_IDLE_TIMEOUT to the 15728 number of idle seconds you want (5min = 300secs). 15729 15730 Note: your VNC viewer side will likely do autorepeating, 15731 so this is no loss unless someone is simultaneously at 15732 the real X display. 15733 15734 Use "-norepeat N" to set how many times norepeat will 15735 be reset if something else (e.g. X session manager) 15736 undoes it. The default is 2. Use a negative value 15737 for unlimited resets. 15738 15739 -nofb Ignore video framebuffer: only process keyboard and 15740 pointer. Intended for use with Win2VNC and x2vnc 15741 dual-monitor setups. 15742 -nobell Do not watch for XBell events. (no beeps will be heard) 15743 Note: XBell monitoring requires the XKEYBOARD extension. 15744 -nosel Do not manage exchange of X selection/cutbuffer between 15745 VNC viewers and the X server at all. 15746 -noprimary Do not poll the PRIMARY selection for changes to send 15747 back to clients. (PRIMARY is still set on received 15748 changes, however). 15749 -nosetprimary Do not set the PRIMARY selection for changes received 15750 from VNC clients. 15751 -noclipboard Do not poll the CLIPBOARD selection for changes to send 15752 back to clients. (CLIPBOARD is still set on received 15753 changes, however). 15754 -nosetclipboard Do not set the CLIPBOARD selection for changes 15755 received from VNC clients. 15756 -seldir string If direction string is "send", only send the selection 15757 to viewers, and if it is "recv" only receive it from 15758 viewers. To work around apps setting the selection 15759 too frequently and messing up the other end. You can 15760 actually supply a comma separated list of directions, 15761 including "debug" to turn on debugging output. 15762 15763 -cursor [mode] Sets how the pointer cursor shape (little icon at the 15764 -nocursor mouse pointer) should be handled. The "mode" string 15765 is optional and is described below. The default 15766 is to show some sort of cursor shape(s). How this 15767 is done depends on the VNC viewer and the X server. 15768 Use -nocursor to disable cursor shapes completely. 15769 15770 Some VNC viewers support the TightVNC CursorPosUpdates 15771 and CursorShapeUpdates extensions (cuts down on 15772 network traffic by not having to send the cursor image 15773 every time the pointer is moved), in which case these 15774 extensions are used (see -nocursorshape and -nocursorpos 15775 below to disable). For other viewers the cursor shape 15776 is written directly to the framebuffer every time the 15777 pointer is moved or changed and gets sent along with 15778 the other framebuffer updates. In this case, there 15779 will be some lag between the vnc viewer pointer and 15780 the remote cursor position. 15781 15782 If the X display supports retrieving the cursor shape 15783 information from the X server, then the default is 15784 to use that mode. On Solaris this can be done with 15785 the SUN_OVL extension using -overlay (see also the 15786 -overlay_nocursor option). A similar overlay scheme 15787 is used on IRIX. Xorg (e.g. Linux) and recent Solaris 15788 Xsun servers support the XFIXES extension to retrieve 15789 the exact cursor shape from the X server. If XFIXES 15790 is present it is preferred over Overlay and is used by 15791 default (see -noxfixes below). This can be disabled 15792 with -nocursor, and also some values of the "mode" 15793 option below. 15794 15795 Note that under XFIXES cursors with transparency (alpha 15796 channel) will usually not be exactly represented and one 15797 may find Overlay preferable. See also the -alphacut 15798 and -alphafrac options below as fudge factors to try 15799 to improve the situation for cursors with transparency 15800 for a given theme. 15801 15802 The "mode" string can be used to fine-tune the 15803 displaying of cursor shapes. It can be used the 15804 following ways: 15805 15806 "-cursor arrow" - just show the standard arrow 15807 nothing more or nothing less. 15808 15809 "-cursor none" - same as "-nocursor" 15810 15811 "-cursor X" - when the cursor appears to be on the 15812 root window, draw the familiar X shape. Some desktops 15813 such as GNOME cover up the root window completely, 15814 and so this will not work, try "X1", etc, to try to 15815 shift the tree depth. On high latency links or slow 15816 machines there will be a time lag between expected and 15817 the actual cursor shape. 15818 15819 "-cursor some" - like "X" but use additional 15820 heuristics to try to guess if the window should have 15821 a windowmanager-like resizer cursor or a text input 15822 I-beam cursor. This is a complete hack, but may be 15823 useful in some situations because it provides a little 15824 more feedback about the cursor shape. 15825 15826 "-cursor most" - try to show as many cursors as 15827 possible. Often this will only be the same as "some" 15828 unless the display has overlay visuals or XFIXES 15829 extensions available. On Solaris and IRIX if XFIXES 15830 is not available, -overlay mode will be attempted. 15831 15832 -cursor_drag Show cursor shape changes even when the mouse is being 15833 dragged with a mouse button down. This is useful if you 15834 want to be able to see Drag-and-Drop cursor icons, etc. 15835 15836 -arrow n Choose an alternate "arrow" cursor from a set of 15837 some common ones. n can be 1 to 6. Default is: 1 15838 Ignored when in XFIXES cursor-grabbing mode. 15839 15840 -noxfixes Do not use the XFIXES extension to draw the exact cursor 15841 shape even if it is available. 15842 15843 Note: To work around a crash in Xorg 1.5 and later 15844 some people needed to use -noxfixes. The Xorg crash 15845 occurred right after a Display Manager (e.g. GDM) login. 15846 Starting with x11vnc 0.9.9 it tries to automatically 15847 avoid using XFIXES until it is sure a window manager 15848 is running. See the -reopen option for more info and 15849 how to use X11VNC_AVOID_WINDOWS=never to disable it. 15850 15851 -alphacut n When using the XFIXES extension for the cursor shape, 15852 cursors with transparency will not usually be displayed 15853 exactly (but opaque ones will). This option sets n as 15854 a cutoff for cursors that have transparency ("alpha 15855 channel" with values ranging from 0 to 255) Any cursor 15856 pixel with alpha value less than n becomes completely 15857 transparent. Otherwise the pixel is completely opaque. 15858 Default 240 15859 15860 -alphafrac fraction With the threshold in -alphacut some cursors will become 15861 almost completely transparent because their alpha values 15862 are not high enough. For those cursors adjust the 15863 alpha threshold until fraction of the non-zero alpha 15864 channel pixels become opaque. Default 0.33 15865 -alpharemove By default, XFIXES cursors pixels with transparency have 15866 the alpha factor multiplied into the RGB color values 15867 (i.e. that corresponding to blending the cursor with a 15868 black background). Specify this option to remove the 15869 alpha factor. (useful for light colored semi-transparent 15870 cursors). 15871 -noalphablend In XFIXES mode do not send cursor alpha channel data 15872 to LibVNCServer. The default is to send it. The 15873 alphablend effect will only be visible in -nocursorshape 15874 mode or for clients with cursorshapeupdates turned 15875 off. (However there is a hack for 32bpp with depth 24, 15876 it uses the extra 8 bits to store cursor transparency 15877 for use with a hacked vncviewer that applies the 15878 transparency locally. See the FAQ for more info). 15879 15880 -nocursorshape Do not use the TightVNC CursorShapeUpdates extension 15881 even if clients support it. See -cursor above. 15882 -cursorpos Option -cursorpos enables sending the X cursor position 15883 -nocursorpos back to all vnc clients that support the TightVNC 15884 CursorPosUpdates extension. Other clients will be able 15885 to see the pointer motions. Default: -cursorpos 15886 -xwarppointer Move the pointer with XWarpPointer(3X) instead of 15887 -noxwarppointer the XTEST extension. Use this as a workaround 15888 if the pointer motion behaves incorrectly, e.g. 15889 on touchscreens or other non-standard setups. 15890 15891 It is also sometimes needed on XINERAMA displays and is 15892 enabled by default if XINERAMA is found to be active. 15893 To prevent this, use -noxwarppointer. 15894 15895 -always_inject Even if there is no displacement (dx = dy = 0) for a 15896 VNC mouse event force the pointer to the indicated x,y 15897 position anyway. Recent (2009) gui toolkits (gnome) 15898 have problems with x11vnc's original mouse input 15899 injection method. So x11vnc's mouse input injection 15900 method has been modified. To regain the OLD behavior 15901 use this option: -always_inject. Then x11vnc will 15902 always force positioning the mouse to the x,y position 15903 even if that position has not changed since the previous 15904 VNC input event. 15905 15906 The first place this problem was noticed was in gnome 15907 terminal: if you pressed and released mouse button 3, a 15908 menu was posted and then its first element 'New Terminal 15909 Window' was activated. This was because x11vnc injected 15910 the mouse position twice: once on ButtonPress and again 15911 on ButtonRelease. The toolkit interpreted the 2nd one 15912 as mouse motion even though the mouse hadn't moved. 15913 So now by default x11vnc tries to avoid injecting the 15914 2nd one. 15915 15916 Note that with the new default x11vnc will be oblivious 15917 to applications moving the pointer (warping) or the 15918 user at the physical display moving it. So it might, 15919 e.g., inject ButtonRelease at the wrong position. 15920 If this (or similar scenarios) causes problems in your 15921 environment, specify -always_inject for the old method. 15922 15923 -buttonmap string String to remap mouse buttons. Format: IJK-LMN, this 15924 maps buttons I -> L, etc., e.g. -buttonmap 13-31 15925 15926 Button presses can also be mapped to keystrokes: replace 15927 a button digit on the right of the dash with :<sym>: 15928 or :<sym1>+<sym2>: etc. for multiple keys. For example, 15929 if the viewing machine has a mouse-wheel (buttons 4 5) 15930 but the x11vnc side does not, these will do scrolls: 15931 -buttonmap 12345-123:Prior::Next: 15932 -buttonmap 12345-123:Up+Up+Up::Down+Down+Down: 15933 15934 See <X11/keysymdef.h> header file for a list of Keysyms, 15935 or use the xev(1) program. Note: mapping of button 15936 clicks to Keysyms may not work if -modtweak or -xkb is 15937 needed for the Keysym. 15938 15939 If you include a modifier like "Shift_L" the 15940 modifier's up/down state is toggled, e.g. to send 15941 "The" use :Shift_L+t+Shift_L+h+e: (the 1st one is 15942 shift down and the 2nd one is shift up). (note: the 15943 initial state of the modifier is ignored and not reset) 15944 To include button events use "Button1", ... etc. 15945 15946 -buttonmap currently does not work on MacOSX console 15947 or in -rawfb mode. 15948 15949 Workaround: use -buttonmap IJ...-LM...=n to limit the 15950 number of mouse buttons to n, e.g. 123-123=3. This will 15951 prevent x11vnc from crashing if the X server reports 15952 there are 5 buttons (4/5 scroll wheel), but there are 15953 only really 3. 15954 15955 -nodragging Do not update the display during mouse dragging events 15956 (mouse button held down). Greatly improves response on 15957 slow setups, but you lose all visual feedback for drags, 15958 text selection, and some menu traversals. It overrides 15959 any -pointer_mode setting. 15960 15961 -ncache n Client-side caching scheme. Framebuffer memory "n" 15962 (an integer) times that of the full display is allocated 15963 below the actual framebuffer to cache screen contents 15964 for rapid retrieval. So a W x H frambuffer is expanded 15965 to a W x (n+1)*H one. Use 0 to disable. 15966 15967 The "n" is actually optional, the default is 10. 15968 15969 For this and the other -ncache* options below you can 15970 abbreviate "-ncache" with "-nc". Also, "-nonc" 15971 is the same as "-ncache 0" 15972 15973 This is an experimental option, currently implemented in 15974 an awkward way in that in the VNC Viewer you can see the 15975 pixel cache contents if you scroll down, etc. So you 15976 will have to set things up so you can't see that region. 15977 If this method is successful, the changes required for 15978 clients to do this less awkwardly will be investigated. 15979 15980 The SSVNC viewer does a good job at automatically hiding 15981 the pixel cache region. Or use SSVNC's -ycrop option 15982 to explicitly hide the region. 15983 15984 Note that this mode consumes a huge amount of memory, 15985 both on the x11vnc server side and on the VNC Viewer 15986 side. If n=2 then the amount of RAM used is roughly 15987 tripled for both x11vnc and the VNC Viewer. As a rule 15988 of thumb, note that 1280x1024 at depth 24 is about 5MB 15989 of pixel data. 15990 15991 For reasonable response when cycling through 4 to 6 15992 large (e.g. web browser) windows a value n of 6 to 12 15993 is recommended. (that's right: ~10X more memory...) 15994 15995 Because of the way window backingstore and saveunders 15996 are implemented, n must be even. It will be incremented 15997 by 1 if it is not. 15998 15999 This mode also works for native MacOS X, but may not 16000 be as effective as the X version. This is due to a 16001 number of things, one is the drop-shadow compositing 16002 that leaves extra areas that need to be repaired (see 16003 -ncache_pad). Another is the window iconification 16004 animations need to be avoided (see -macicontime). 16005 It appears the that the 'Scale' animation mode gives 16006 better results than the 'Genie' one. Also, window event 16007 detection not as accurate as the X version. 16008 16009 -ncache_cr In -ncache mode, try to do copyrect opaque window 16010 moves/drags instead of wireframes (this can induce 16011 painting errors). The wireframe will still be used when 16012 moving a window whose save-unders has not yet been set 16013 or has been invalidated. 16014 16015 Some VNC Viewers provide better response than others 16016 with this option. On Unix, realvnc viewer gives 16017 smoother drags than tightvnc viewer. Response may also 16018 be choppy if the server side machine is too slow. 16019 16020 Sometimes on very slow modem connections, this actually 16021 gives an improvement because no pixel data at all 16022 (not even the box animation) is sent during the drag. 16023 16024 -ncache_no_moveraise In -ncache mode, do not assume that moving a window 16025 will cause the window manager to raise it to the top 16026 of the stack. The default is to assume it does, and 16027 so at the beginning of any wireframe, etc, window moves 16028 the window will be pushed to top in the VNC viewer. 16029 16030 -ncache_no_dtchange In -ncache mode, do not try to guess when the desktop 16031 (viewport) changes to another one (i.e. another 16032 workarea). The default is to try to guess and when 16033 detected try to make the transistion more smoothly. 16034 16035 -ncache_no_rootpixmap In -ncache mode, do not try to snapshot the desktop 16036 background to use in guessing or reconstructing window 16037 save-unders. 16038 16039 -ncache_keep_anims In -ncache mode, do not try to disable window 16040 manager animations and other effects (that usually 16041 degrade ncache performance or cause painting errors). 16042 The default is to try to disable them on KDE (but not 16043 GNOME) when VNC clients are connected. 16044 16045 For other window managers or desktops that provide 16046 animations, effects, compositing, translucency, 16047 etc. that interfere with the -ncache method you will 16048 have to disable them manually. 16049 16050 -ncache_old_wm In -ncache mode, enable some heuristics for old style 16051 window managers such as fvwm and twm. 16052 16053 -ncache_pad n In -ncache mode, pad each window with n pixels for the 16054 caching rectangles. This can be used to try to improve 16055 the situation with dropshadows or other compositing 16056 (e.g. MacOS X window manager), although it could make 16057 things worse. The default is 0 on Unix and 24 on 16058 MacOS X. 16059 -debug_ncache Turn on debugging and profiling output under -ncache. 16060 16061 -wireframe [str] Try to detect window moves or resizes when a mouse 16062 -nowireframe button is held down and show a wireframe instead of 16063 the full opaque window. This is based completely on 16064 heuristics and may not always work: it depends on your 16065 window manager and even how you move things around. 16066 See -pointer_mode below for discussion of the "bogging 16067 down" problem this tries to avoid. 16068 Default: -wireframe 16069 16070 Shorter aliases: -wf [str] and -nowf 16071 16072 The value "str" is optional and, of course, is 16073 packed with many tunable parameters for this scheme: 16074 16075 Format: shade,linewidth,percent,T+B+L+R,mod,t1+t2+t3+t4 16076 Default: 0xff,2,0,32+8+8+8,all,0.15+0.30+5.0+0.125 16077 16078 If you leave nothing between commas: ",," the default 16079 value is used. If you don't specify enough commas, 16080 the trailing parameters are set to their defaults. 16081 16082 "shade" indicate the "color" for the wireframe, 16083 usually a greyscale: 0-255, however for 16 and 32bpp you 16084 can specify an rgb.txt X color (e.g. "dodgerblue") or 16085 a value > 255 is treated as RGB (e.g. red is 0xff0000). 16086 "linewidth" sets the width of the wireframe in pixels. 16087 "percent" indicates to not apply the wireframe scheme 16088 to windows with area less than this percent of the 16089 full screen. 16090 16091 "T+B+L+R" indicates four integers for how close in 16092 pixels the pointer has to be from the Top, Bottom, Left, 16093 or Right edges of the window to consider wireframing. 16094 This is a speedup to quickly exclude a window from being 16095 wireframed: set them all to zero to not try the speedup 16096 (scrolling and selecting text will likely be slower). 16097 16098 "mod" specifies if a button down event in the 16099 interior of the window with a modifier key (Alt, Shift, 16100 etc.) down should indicate a wireframe opportunity. 16101 It can be "0" or "none" to skip it, "1" or "all" 16102 to apply it to any modifier, or "Shift", "Alt", 16103 "Control", "Meta", "Super", or "Hyper" to only 16104 apply for that type of modifier key. 16105 16106 "t1+t2+t3+t4" specify four floating point times in 16107 seconds: t1 is how long to wait for the pointer to move, 16108 t2 is how long to wait for the window to start moving 16109 or being resized (for some window managers this can be 16110 rather long), t3 is how long to keep a wireframe moving 16111 before repainting the window. t4 is the minimum time 16112 between sending wireframe "animations". If a slow 16113 link is detected, these values may be automatically 16114 changed to something better for a slow link. 16115 16116 -nowireframelocal By default, mouse motion and button presses of a 16117 user sitting at the LOCAL display are monitored for 16118 wireframing opportunities (so that the changes will be 16119 sent efficiently to the VNC clients). Use this option 16120 to disable this behavior. 16121 16122 -wirecopyrect mode Since the -wireframe mechanism evidently tracks moving 16123 -nowirecopyrect windows accurately, a speedup can be obtained by 16124 telling the VNC viewers to locally copy the translated 16125 window region. This is the VNC CopyRect encoding: 16126 the framebuffer update doesn't need to send the actual 16127 new image data. 16128 16129 Shorter aliases: -wcr [mode] and -nowcr 16130 16131 "mode" can be "never" (same as -nowirecopyrect) 16132 to never try the copyrect, "top" means only do it if 16133 the window was not covered by any other windows, and 16134 "always" means to translate the orginally unobscured 16135 region (this may look odd as the remaining pieces come 16136 in, but helps on a slow link). Default: "always" 16137 16138 Note: there can be painting errors or slow response 16139 when using -scale so you may want to disable CopyRect 16140 in this case "-wirecopyrect never" on the command 16141 line or by remote-control. Or you can also use the 16142 "-scale xxx:nocr" scale option. 16143 16144 -debug_wireframe Turn on debugging info printout for the wireframe 16145 heuristics. "-dwf" is an alias. Specify multiple 16146 times for more output. 16147 16148 -scrollcopyrect mode Like -wirecopyrect, but use heuristics to try to guess 16149 -noscrollcopyrect if a window has scrolled its contents (either vertically 16150 or horizontally). This requires the RECORD X extension 16151 to "snoop" on X applications (currently for certain 16152 XCopyArea and XConfigureWindow X protocol requests). 16153 Examples: Hitting <Return> in a terminal window when the 16154 cursor was at the bottom, the text scrolls up one line. 16155 Hitting <Down> arrow in a web browser window, the web 16156 page scrolls up a small amount. Or scrolling with a 16157 scrollbar or mouse wheel. 16158 16159 Shorter aliases: -scr [mode] and -noscr 16160 16161 This scheme will not always detect scrolls, but when 16162 it does there is a nice speedup from using the VNC 16163 CopyRect encoding (see -wirecopyrect). The speedup 16164 is both in reduced network traffic and reduced X 16165 framebuffer polling/copying. On the other hand, it may 16166 induce undesired transients (e.g. a terminal cursor 16167 being scrolled up when it should not be) or other 16168 painting errors (window tearing, bunching-up, etc). 16169 These are automatically repaired in a short period 16170 of time. If this is unacceptable disable the feature 16171 with -noscrollcopyrect. 16172 16173 Screen clearing kludges: for testing at least, there 16174 are some "magic key sequences" (must be done in less 16175 than 1 second) to aid repairing painting errors that 16176 may be seen when using this mode: 16177 16178 3 Alt_L's in a row: resend whole screen, 16179 4 Alt_L's in a row: reread and resend whole screen, 16180 3 Super_L's in a row: mark whole screen for polling, 16181 4 Super_L's in a row: reset RECORD context, 16182 5 Super_L's in a row: try to push a black screen 16183 16184 note: Alt_L is the Left "Alt" key (a single key) 16185 Super_L is the Left "Super" key (Windows flag). 16186 Both of these are modifier keys, and so should not 16187 generate characters when pressed by themselves. Also, 16188 your VNC viewer may have its own refresh hot-key 16189 or button. 16190 16191 "mode" can be "never" (same as -noscrollcopyrect) 16192 to never try the copyrect, "keys" means to try it 16193 in response to keystrokes only, "mouse" means to 16194 try it in response to mouse events only, "always" 16195 means to do both. Default: "always" 16196 16197 Note: there can be painting errors or slow response 16198 when using -scale so you may want to disable CopyRect 16199 in this case "-scrollcopyrect never" on the command 16200 line or by remote-control. Or you can also use the 16201 "-scale xxx:nocr" scale option. 16202 16203 -scr_area n Set the minimum area in pixels for a rectangle 16204 to be considered for the -scrollcopyrect detection 16205 scheme. This is to avoid wasting the effort on small 16206 rectangles that would be quickly updated the normal way. 16207 E.g. suppose an app updated the position of its skinny 16208 scrollbar first and then shifted the large panel 16209 it controlled. We want to be sure to skip the small 16210 scrollbar and get the large panel. Default: 60000 16211 16212 -scr_skip list Skip scroll detection for applications matching 16213 the comma separated list of strings in "list". 16214 Some applications implement their scrolling in 16215 strange ways where the XCopyArea, etc, also applies 16216 to invisible portions of the window: if we CopyRect 16217 those areas it looks awful during the scroll and 16218 there may be painting errors left after the scroll. 16219 Soffice.bin is the worst known offender. 16220 16221 Use "##" to denote the start of the application class 16222 (e.g. "##XTerm") and "++" to denote the start 16223 of the application instance name (e.g. "++xterm"). 16224 The string your list is matched against is of the form 16225 "^^WM_NAME##Class++Instance<same-for-any-subwindows>" 16226 The "xlsclients -la" command will provide this info. 16227 16228 If a pattern is prefixed with "KEY:" it only applies 16229 to Keystroke generated scrolls (e.g. Up arrow). If it 16230 is prefixed with "MOUSE:" it only applies to Mouse 16231 induced scrolls (e.g. dragging on a scrollbar). 16232 Default: ##Soffice.bin,##StarOffice,##OpenOffice 16233 16234 -scr_inc list Opposite of -scr_skip: this list is consulted first 16235 and if there is a match the window will be monitored 16236 via RECORD for scrolls irrespective of -scr_skip. 16237 Use -scr_skip '*' to skip anything that does not match 16238 your -scr_inc. Use -scr_inc '*' to include everything. 16239 16240 -scr_keys list For keystroke scroll detection, only apply the RECORD 16241 heuristics to the comma separated list of keysyms in 16242 "list". You may find the RECORD overhead for every 16243 one of your keystrokes disrupts typing too much, but you 16244 don't want to turn it off completely with "-scr mouse" 16245 and -scr_parms does not work or is too confusing. 16246 16247 The listed keysyms can be numeric or the keysym 16248 names in the <X11/keysymdef.h> header file or from the 16249 xev(1) program. Example: "-scr_keys Up,Down,Return". 16250 One probably wants to have application specific lists 16251 (e.g. for terminals, etc) but that is too icky to think 16252 about for now... 16253 16254 If "list" begins with the "-" character the list 16255 is taken as an exclude list: all keysyms except those 16256 list will be considered. The special string "builtin" 16257 expands to an internal list of keysyms that are likely 16258 to cause scrolls. BTW, by default modifier keys, 16259 Shift_L, Control_R, etc, are skipped since they almost 16260 never induce scrolling by themselves. 16261 16262 -scr_term list Yet another cosmetic kludge. Apply shell/terminal 16263 heuristics to applications matching comma separated 16264 list (same as for -scr_skip/-scr_inc). For example an 16265 annoying transient under scroll detection is if you 16266 hit Enter in a terminal shell with full text window, 16267 the solid text cursor block will be scrolled up. 16268 So for a short time there are two (or more) block 16269 cursors on the screen. There are similar scenarios, 16270 (e.g. an output line is duplicated). 16271 16272 These transients are induced by the approximation of 16273 scroll detection (e.g. it detects the scroll, but not 16274 the fact that the block cursor was cleared just before 16275 the scroll). In nearly all cases these transient errors 16276 are repaired when the true X framebuffer is consulted 16277 by the normal polling. But they are distracting, so 16278 what this option provides is extra "padding" near the 16279 bottom of the terminal window: a few extra lines near 16280 the bottom will not be scrolled, but rather updated 16281 from the actual X framebuffer. This usually reduces 16282 the annoying artifacts. Use "none" to disable. 16283 Default: "term" 16284 16285 -scr_keyrepeat lo-hi If a key is held down (or otherwise repeats rapidly) and 16286 this induces a rapid sequence of scrolls (e.g. holding 16287 down an Arrow key) the "scrollcopyrect" detection 16288 and overhead may not be able to keep up. A time per 16289 single scroll estimate is performed and if that estimate 16290 predicts a sustainable scrollrate of keys per second 16291 between "lo" and "hi" then repeated keys will be 16292 DISCARDED to maintain the scrollrate. For example your 16293 key autorepeat may be 25 keys/sec, but for a large 16294 window or slow link only 8 scrolls per second can be 16295 sustained, then roughly 2 out of every 3 repeated keys 16296 will be discarded during this period. Default: "4-20" 16297 16298 -scr_parms string Set various parameters for the scrollcopyrect mode. 16299 The format is similar to that for -wireframe and packed 16300 with lots of parameters: 16301 16302 Format: T+B+L+R,t1+t2+t3,s1+s2+s3+s4+s5 16303 Default: 0+64+32+32,0.02+0.10+0.9,0.03+0.06+0.5+0.1+5.0 16304 16305 If you leave nothing between commas: ",," the default 16306 value is used. If you don't specify enough commas, 16307 the trailing parameters are set to their defaults. 16308 16309 "T+B+L+R" indicates four integers for how close in 16310 pixels the pointer has to be from the Top, Bottom, Left, 16311 or Right edges of the window to consider scrollcopyrect. 16312 If -wireframe overlaps it takes precedence. This is a 16313 speedup to quickly exclude a window from being watched 16314 for scrollcopyrect: set them all to zero to not try 16315 the speedup (things like selecting text will likely 16316 be slower). 16317 16318 "t1+t2+t3" specify three floating point times in 16319 seconds that apply to scrollcopyrect detection with 16320 *Keystroke* input: t1 is how long to wait after a key 16321 is pressed for the first scroll, t2 is how long to keep 16322 looking after a Keystroke scroll for more scrolls. 16323 t3 is how frequently to try to update surrounding 16324 scrollbars outside of the scrolling area (0.0 to 16325 disable) 16326 16327 "s1+s2+s3+s4+s5" specify five floating point times 16328 in seconds that apply to scrollcopyrect detection with 16329 *Mouse* input: s1 is how long to wait after a mouse 16330 button is pressed for the first scroll, s2 is how long 16331 to keep waiting for additional scrolls after the first 16332 Mouse scroll was detected. s3 is how frequently to 16333 try to update surrounding scrollbars outside of the 16334 scrolling area (0.0 to disable). s4 is how long to 16335 buffer pointer motion (to try to get fewer, bigger 16336 mouse scrolls). s5 is the maximum time to spend just 16337 updating the scroll window without updating the rest 16338 of the screen. 16339 16340 -fixscreen string Periodically "repair" the screen based on settings 16341 in "string". Hopefully you won't need this option, 16342 it is intended for cases when the -scrollcopyrect or 16343 -wirecopyrect features leave too many painting errors, 16344 but it can be used for any scenario. This option 16345 periodically performs costly operations and so 16346 interactive response may be reduced when it is on. 16347 You can use 3 Alt_L's (the Left "Alt" key) taps in 16348 a row (as described under -scrollcopyrect) instead to 16349 manually request a screen repaint when it is needed. 16350 16351 "string" is a comma separated list of one or more of 16352 the following: "V=t", "C=t", "X=t", and "8=t". 16353 In these "t" stands for a time in seconds (it is 16354 a floating point even though one should usually use 16355 values > 2 to avoid wasting resources). V sets how 16356 frequently the entire screen should be sent to viewers 16357 (it is like the 3 Alt_L's). C sets how long to wait 16358 after a CopyRect to repaint the full screen. X sets 16359 how frequently to reread the full X11 framebuffer from 16360 the X server and push it out to connected viewers. 16361 Use of X should be rare, please report a bug if you 16362 find you need it. 8= applies only for -8to24 mode: it 16363 sets how often the non-default visual regions of the 16364 screen (e.g. 8bpp windows) are refreshed. Examples: 16365 -fixscreen V=10 -fixscreen C=10 16366 16367 -debug_scroll Turn on debugging info printout for the scroll 16368 heuristics. "-ds" is an alias. Specify it multiple 16369 times for more output. 16370 16371 -noxrecord Disable any use of the RECORD extension. This is 16372 currently used by the -scrollcopyrect scheme and to 16373 monitor X server grabs. 16374 16375 -grab_buster Some of the use of the RECORD extension can leave a 16376 -nograb_buster tiny window for XGrabServer deadlock. This is only if 16377 the whole-server grabbing application expects mouse or 16378 keyboard input before releasing the grab. It is usually 16379 a window manager that does this. x11vnc takes care to 16380 avoid the problem, but if caught x11vnc will freeze. 16381 Without -grab_buster, the only solution is to go the 16382 physical display and give it some input to satisfy the 16383 grabbing app. Or manually kill and restart the window 16384 manager if that is feasible. With -grab_buster, x11vnc 16385 will fork a helper thread and if x11vnc appears to be 16386 stuck in a grab after a period of time (20-30 sec) then 16387 it will inject some user input: button clicks, Escape, 16388 mouse motion, etc to try to break the grab. If you 16389 experience a lot of grab deadlock, please report a bug. 16390 16391 -debug_grabs Turn on debugging info printout with respect to 16392 XGrabServer() deadlock for -scrollcopyrect mode. 16393 16394 -debug_sel Turn on debugging info printout with respect to 16395 PRIMARY, CLIPBOARD, and CUTBUFFER0 selections. 16396 16397 -pointer_mode n Various pointer motion update schemes. "-pm" is 16398 an alias. The problem is pointer motion can cause 16399 rapid changes on the screen: consider the rapid 16400 changes when you drag a large window around opaquely. 16401 Neither x11vnc's screen polling and vnc compression 16402 routines nor the bandwidth to the vncviewers can keep 16403 up these rapid screen changes: everything will bog down 16404 when dragging or scrolling. So a scheme has to be used 16405 to "eat" much of that pointer input before re-polling 16406 the screen and sending out framebuffer updates. The 16407 mode number "n" can be 0 to 4 and selects one of 16408 the schemes desribed below. 16409 16410 Note that the -wireframe and -scrollcopyrect modes 16411 complement -pointer_mode by detecting (and improving) 16412 certain periods of "rapid screen change". 16413 16414 n=0: does the same as -nodragging. (all screen polling 16415 is suspended if a mouse button is pressed.) 16416 16417 n=1: was the original scheme used to about Jan 2004: 16418 it basically just skips -input_skip keyboard or pointer 16419 events before repolling the screen. 16420 16421 n=2 is an improved scheme: by watching the current rate 16422 of input events it tries to detect if it should try to 16423 "eat" additional pointer events before continuing. 16424 16425 n=3 is basically a dynamic -nodragging mode: it detects 16426 when the mouse motion has paused and then refreshes 16427 the display. 16428 16429 n=4 attempts to measures network rates and latency, 16430 the video card read rate, and how many tiles have been 16431 changed on the screen. From this, it aggressively tries 16432 to push screen "frames" when it decides it has enough 16433 resources to do so. NOT FINISHED. 16434 16435 The default n is 2. Note that modes 2, 3, 4 will skip 16436 -input_skip keyboard events (but it will not count 16437 pointer events). Also note that these modes are not 16438 available in -threads mode which has its own pointer 16439 event handling mechanism. 16440 16441 To try out the different pointer modes to see which 16442 one gives the best response for your usage, it is 16443 convenient to use the remote control function, for 16444 example "x11vnc -R pm:4" or the tcl/tk gui (Tuning -> 16445 pointer_mode -> n). 16446 16447 -input_skip n For the pointer handling when non-threaded: try to 16448 read n user input events before scanning display. n < 0 16449 means to act as though there is always user input. 16450 Default: 10 16451 16452 -allinput Have x11vnc read and process all available client input 16453 before proceeding. 16454 16455 -input_eagerly Similar to -allinput but use the handleEventsEagerly 16456 mechanism built into LibVNCServer. 16457 16458 -speeds rd,bw,lat x11vnc tries to estimate some speed parameters that 16459 are used to optimize scheduling (e.g. -pointer_mode 16460 4, -wireframe, -scrollcopyrect) and other things. 16461 Use the -speeds option to set these manually. 16462 The triple "rd,bw,lat" corresponds to video h/w 16463 read rate in MB/sec, network bandwidth to clients in 16464 KB/sec, and network latency to clients in milliseconds, 16465 respectively. If a value is left blank, e.g. "-speeds 16466 ,100,15", then the internal scheme is used to estimate 16467 the empty value(s). 16468 16469 Typical PC video cards have read rates of 5-10 MB/sec. 16470 If the framebuffer is in main memory instead of video 16471 h/w (e.g. SunRay, shadowfb, dummy driver, Xvfb), the 16472 read rate may be much faster. "x11perf -getimage500" 16473 can be used to get a lower bound (remember to factor 16474 in the bytes per pixel). It is up to you to estimate 16475 the network bandwith and latency to clients. For the 16476 latency the ping(1) command can be used. 16477 16478 For convenience there are some aliases provided, 16479 e.g. "-speeds modem". The aliases are: "modem" for 16480 6,4,200; "dsl" for 6,100,50; and "lan" for 6,5000,1 16481 16482 -wmdt string For some features, e.g. -wireframe and -scrollcopyrect, 16483 x11vnc has to work around issues for certain window 16484 managers or desktops (currently kde and xfce). 16485 By default it tries to guess which one, but it can 16486 guess incorrectly. Use this option to indicate which 16487 wm/dt. "string" can be "gnome", "kde", "cde", 16488 "xfce", or "root" (classic X wm). Anything else 16489 is interpreted as "root". 16490 16491 -debug_pointer Print debugging output for every pointer event. 16492 -debug_keyboard Print debugging output for every keyboard event. 16493 Same as -dp and -dk, respectively. Use multiple 16494 times for more output. 16495 16496 -defer time Time in ms to delay sending updates to connected clients 16497 (deferUpdateTime) Default: 20 16498 16499 -wait time Time in ms to pause between screen polls. Used to cut 16500 down on load. Default: 20 16501 16502 -extra_fbur n Perform extra FrameBufferUpdateRequests checks to 16503 try to be in better sync with the client's requests. 16504 What this does is perform extra polls of the client 16505 socket at critical times (before '-defer' and '-wait' 16506 calls.) The default is n=1. Set to a larger number to 16507 insert more checks or set to n=0 to disable. A downside 16508 of these extra calls is that more mouse input may be 16509 processed than desired. 16510 16511 -wait_ui factor Factor by which to cut the -wait time if there 16512 has been recent user input (pointer or keyboard). 16513 Improves response, but increases the load whenever you 16514 are moving the mouse or typing. Default: 2.00 16515 -setdefer n When the -wait_ui mechanism cuts down the wait time ms, 16516 set the defer time to the same ms value. n=1 to enable, 16517 0 to disable, and -1 to set defer to 0 (no delay). 16518 Similarly, 2 and -2 indicate 'urgent_update' mode should 16519 be used to push the updates even sooner. Default: 1 16520 -nowait_bog Do not detect if the screen polling is "bogging down" 16521 and sleep more. Some activities with no user input can 16522 slow things down a lot: consider a large terminal window 16523 with a long build running in it continuously streaming 16524 text output. By default x11vnc will try to detect this 16525 (3 screen polls in a row each longer than 0.25 sec with 16526 no user input), and sleep up to 1.5 secs to let things 16527 "catch up". Use this option to disable that detection. 16528 -slow_fb time Floating point time in seconds to delay all screen 16529 polling. For special purpose usage where a low frame 16530 rate is acceptable and desirable, but you want the 16531 user input processed at the normal rate so you cannot 16532 use -wait. 16533 -xrefresh time Floating point time in seconds to indicate how often to 16534 do the equivalent of xrefresh(1) to force all windows 16535 (in the viewable area if -id, -sid, or -clip is used) 16536 to repaint themselves. Use this only if applications 16537 misbehave by not repainting themselves properly. 16538 See also -noxdamage. 16539 -nap Monitor activity and if it is low take longer naps 16540 -nonap between screen polls to really cut down load when idle. 16541 Default: take naps 16542 -sb time Time in seconds after NO activity (e.g. screen blank) 16543 to really throttle down the screen polls (i.e. sleep 16544 for about 1.5 secs). Use 0 to disable. Default: 60 16545 Set the env. var. X11VNC_SB_FACTOR to scale it. 16546 16547 -readtimeout n Set LibVNCServer rfbMaxClientWait to n seconds. On 16548 slow links that take a long time to paint the first 16549 screen LibVNCServer may hit the timeout and drop the 16550 connection. Default: 20 seconds. 16551 -ping n Send a 1x1 framebuffer update to all clients every n 16552 seconds (e.g. to try to keep a network connection alive) 16553 16554 -nofbpm If the system supports the FBPM (Frame Buffer Power 16555 -fbpm Management) extension (i.e. some Sun systems), then 16556 prevent the video h/w from going into a reduced power 16557 state when VNC clients are connected. 16558 16559 FBPM capable video h/w save energy when the workstation 16560 is idle by going into low power states (similar to DPMS 16561 for monitors). This interferes with x11vnc's polling 16562 of the framebuffer data. 16563 16564 "-nofbpm" means prevent FBPM low power states whenever 16565 VNC clients are connected, while "-fbpm" means to not 16566 monitor the FBPM state at all. See the xset(1) manpage 16567 for details. -nofbpm is basically the same as running 16568 "xset fbpm force on" periodically. Default: -fbpm 16569 16570 -nodpms If the system supports the DPMS (Display Power Managemen 16571 t 16572 -dpms Signaling) extension, then prevent the monitor from 16573 going into a reduced power state when VNC clients 16574 are connected. 16575 16576 DPMS reduced power monitor states are a good thing 16577 and you normally want the power down to take place 16578 (usually x11vnc has no problem exporting the display in 16579 this state). You probably only want to use "-nodpms" 16580 to work around problems with Screen Savers kicking 16581 on in DPMS low power states. There is known problem 16582 with kdesktop_lock on KDE where the screen saver keeps 16583 kicking in every time user input stops for a second 16584 or two. Specifying "-nodpms" works around it. 16585 16586 "-nodpms" means prevent DPMS low power states whenever 16587 VNC clients are connected, while "-dpms" means to not 16588 monitor the DPMS state at all. See the xset(1) manpage 16589 for details. -nodpms is basically the same as running 16590 "xset dpms force on" periodically. Default: -dpms 16591 16592 -forcedpms If the system supports the DPMS (Display Power 16593 Management Signaling) extension, then try to keep the 16594 monitor in a powered off state. This is to prevent 16595 nosey people at the physical display from viewing what 16596 is on the screen. Be sure to lock the screen before 16597 disconnecting. 16598 16599 This method is far from bullet proof, e.g. suppose 16600 someone attaches a non-DPMS monitor, or loads the 16601 machine so that there is a gap of time before x11vnc 16602 restores the powered off state? On many machines if 16603 he floods it with keyboard and mouse input he can see 16604 flashes of what is on the screen before the DPMS off 16605 state is reestablished. For this to work securely 16606 there would need to be support in the X server to do 16607 this exactly rather than approximately with DPMS. 16608 16609 -clientdpms As -forcedpms but only when VNC clients are connected. 16610 16611 -noserverdpms The UltraVNC ServerInput extension is supported. 16612 This allows the VNC viewer to click a button that will 16613 cause the server (x11vnc) to try to disable keyboard 16614 and mouse input at the physical display and put the 16615 monitor in dpms powered off state. Use this option to 16616 skip powering off the monitor. 16617 16618 -noultraext Disable the following UltraVNC extensions: SingleWindow 16619 and ServerInput. The others managed by LibVNCServer 16620 (textchat, 1/n scaling, rfbEncodingUltra) are not. 16621 16622 -chatwindow Place a local UltraVNC chat window on the X11 display 16623 that x11vnc is polling. That way the person on the VNC 16624 viewer-side can chat with the person at the physical 16625 X11 console. (e.g. helpdesk w/o telephone) 16626 16627 For this to work the SSVNC package (version 1.0.21 or 16628 later) MUST BE installed on the system where x11vnc runs 16629 and the 'ssvnc' command must be available in $PATH. 16630 The ssvncviewer is used as a chat window helper. 16631 See http://www.karlrunge.com/x11vnc/ssvnc.html 16632 16633 This option implies '-rfbversion 3.6' so as to trick 16634 UltraVNC viewers, otherwise they assume chat is not 16635 available. To specify a different rfbversion, place 16636 it after the -chatwindow option on the cmdline. 16637 16638 See also the remote control 'chaton' and 'chatoff' 16639 actions. These can also be set from the tkx11vnc GUI. 16640 16641 -noxdamage Do not use the X DAMAGE extension to detect framebuffer 16642 changes even if it is available. Use -xdamage if your 16643 default is to have it off. 16644 16645 x11vnc's use of the DAMAGE extension: 1) significantly 16646 reduces the load when the screen is not changing much, 16647 and 2) detects changed areas (small ones by default) 16648 more quickly. 16649 16650 Currently the DAMAGE extension is overly conservative 16651 and often reports large areas (e.g. a whole terminal 16652 or browser window) as damaged even though the actual 16653 changed region is much smaller (sometimes just a few 16654 pixels). So heuristics were introduced to skip large 16655 areas and use the damage rectangles only as "hints" 16656 for the traditional scanline polling. The following 16657 tuning parameters are introduced to adjust this 16658 behavior: 16659 16660 -xd_area A Set the largest DAMAGE rectangle area "A" (in 16661 pixels: width * height) to trust as truly damaged: 16662 the rectangle will be copied from the framebuffer 16663 (slow) no matter what. Set to zero to trust *all* 16664 rectangles. Default: 20000 16665 -xd_mem f Set how long DAMAGE rectangles should be "remembered", 16666 "f" is a floating point number and is in units of the 16667 scanline repeat cycle time (32 iterations). The default 16668 (1.0) should give no painting problems. Increase it if 16669 there are problems or decrease it to live on the edge 16670 (perhaps useful on a slow machine). 16671 16672 -sigpipe string Broken pipe (SIGPIPE) handling. "string" can be 16673 "ignore" or "exit". For "ignore" LibVNCServer 16674 will handle the abrupt loss of a client and continue, 16675 for "exit" x11vnc will cleanup and exit at the 1st 16676 broken connection. 16677 16678 This option is not really needed since LibVNCServer 16679 is doing the correct thing now for quite some time. 16680 However, for convenience you can use it to ignore other 16681 signals, e.g. "-sigpipe ignore:HUP,INT,TERM" in case 16682 that would be useful for some sort of application. 16683 You can also put "exit:.." in the list to have x11vnc 16684 cleanup on the listed signals. "-sig" is an alias 16685 for this option if you don't like the 'pipe'. Example: 16686 -sig ignore:INT,TERM,exit:USR1 16687 16688 -threads Whether or not to use the threaded LibVNCServer 16689 -nothreads algorithm [rfbRunEventLoop] if libpthread is available. 16690 In this mode new threads (one for input and one 16691 for output) are created to handle each new client. 16692 Default: -nothreads. 16693 16694 Thread stability is much improved in version 0.9.8. 16695 16696 Multiple clients in threaded mode should be stable 16697 for the ZRLE encoding on all platforms. The Tight and 16698 Zlib encodings are currently only stable on Linux for 16699 multiple clients. Compile with -DTLS=__thread if your 16700 OS and compiler and linker support it. 16701 16702 For resizes (randr, etc.) set this env. var. to the numb 16703 er 16704 of milliseconds to sleep: X11VNC_THREADS_NEW_FB_SLEEP 16705 at various places in the do_new_fb() action. This is to 16706 let various activities settle. Default is about 500ms. 16707 16708 Multiple clients in threaded mode could yield better 16709 performance for 'class-room' broadcasting usage; also in 16710 -appshare broadcast mode. See also the -reflect option. 16711 16712 -fs f If the fraction of changed tiles in a poll is greater 16713 than f, the whole screen is updated. Default: 0.75 16714 -gaps n Heuristic to fill in gaps in rows or cols of n or 16715 less tiles. Used to improve text paging. Default: 4 16716 -grow n Heuristic to grow islands of changed tiles n or wider 16717 by checking the tile near the boundary. Default: 3 16718 -fuzz n Tolerance in pixels to mark a tiles edges as changed. 16719 Default: 2 16720 -debug_tiles Print debugging output for tiles, fb updates, etc. 16721 16722 -snapfb Instead of polling the X display framebuffer (fb) 16723 for changes, periodically copy all of X display fb 16724 into main memory and examine that copy for changes. 16725 (This setting also applies for non-X -rawfb modes). 16726 Under some circumstances this will improve interactive 16727 response, or at least make things look smoother, but in 16728 others (most!) it will make the response worse. If the 16729 video h/w fb is such that reading small tiles is very 16730 slow this mode could help. To keep the "framerate" 16731 up the screen size x bpp cannot be too large. Note that 16732 this mode is very wasteful of memory I/O resources 16733 (it makes full screen copies even if nothing changes). 16734 It may be of use in video capture-like applications, 16735 webcams, or where window tearing is a problem. 16736 16737 -rawfb string Instead of polling X, poll the memory object specified 16738 in "string". 16739 16740 For file polling, to memory map mmap(2) a file use: 16741 "map:/path/to/a/file@WxHxB", with framebuffer Width, 16742 Height, and Bits per pixel. "mmap:..." is the 16743 same. 16744 16745 If there is trouble with mmap, use "file:/..." 16746 for slower lseek(2) based reading. 16747 16748 Use "snap:..." to imply -snapfb mode and the "file:" 16749 access (this is for unseekable devices that only provide 16750 the fb all at once, e.g. a video camera provides the 16751 whole frame). 16752 16753 For shared memory segments string is of the form: 16754 "shm:N@WxHxB" which specifies a shmid N and with 16755 WxHxB as above. See shmat(1) and ipcs(1) 16756 16757 If you do not supply a type "map" is assumed if 16758 the file exists (see the next paragraphs for some 16759 exceptions to this.) 16760 16761 If string is "setup:cmd", then the command "cmd" 16762 is run and the first line from it is read and used 16763 as "string". This allows initializing the device, 16764 determining WxHxB, etc. These are often done as root 16765 so take care. 16766 16767 If the string begins with "video", see the VIDEO4LINUX 16768 discussion below where the device may be queried for 16769 (and possibly set) the framebuffer parameters. 16770 16771 If the string begins with "console", "/dev/fb", 16772 "fb", or "vt", see the LINUX CONSOLE discussion 16773 below where the framebuffer device is opened and 16774 keystrokes (and possibly mouse events) are inserted 16775 into the console. 16776 16777 If the string begins with "vnc", see the VNC HOST 16778 discussion below where the framebuffer is taken as that 16779 of another remote VNC server. 16780 16781 Optional suffixes are ":R/G/B" and "+O" to specify 16782 red, green, and blue masks (in hex) and an offset into 16783 the memory object. If the masks are not provided x11vnc 16784 guesses them based on the bpp (if the colors look wrong, 16785 you need to provide the masks.) 16786 16787 Another optional suffix is the Bytes Per Line which in 16788 some cases is not WxB/8. Specify it as WxHxB-BPL 16789 e.g. 800x600x16-2048. This could be a normal width 16790 1024 at 16bpp fb, but only width 800 shows up. 16791 16792 So the full format is: mode:file@WxHxB:R/G/B+O-BPL 16793 16794 Examples: 16795 -rawfb shm:210337933@800x600x32:ff/ff00/ff0000 16796 -rawfb map:/dev/fb0@1024x768x32 16797 -rawfb map:/tmp/Xvfb_screen0@640x480x8+3232 16798 -rawfb file:/tmp/my.pnm@250x200x24+37 16799 -rawfb file:/dev/urandom@128x128x8 16800 -rawfb snap:/dev/video0@320x240x24 -24to32 16801 -rawfb video0 16802 -rawfb video -pipeinput VID 16803 -rawfb console 16804 -rawfb vt2 16805 -rawfb vnc:somehost:0 16806 16807 (see ipcs(1) and fbset(1) for the first two examples) 16808 16809 In general all user input is discarded by default (see 16810 the -pipeinput option for how to use a helper program 16811 to insert). Most of the X11 (screen, keyboard, mouse) 16812 options do not make sense and many will cause this 16813 mode to crash, so please think twice before setting or 16814 changing them in a running x11vnc. 16815 16816 If you DO NOT want x11vnc to close the X DISPLAY in 16817 rawfb mode, prepend a "+" e.g. +file:/dev/fb0... 16818 Keeping the display open enables the default 16819 remote-control channel, which could be useful. 16820 Alternatively, if you specify -noviewonly, then the 16821 mouse and keyboard input are STILL sent to the X 16822 display, this usage should be very rare, i.e. doing 16823 something strange with /dev/fb0. 16824 16825 If the device is not "seekable" (e.g. webcam) try 16826 reading it all at once in full snaps via the "snap:" 16827 mode (note: this is a resource hog). If you are using 16828 file: or map: AND the device needs to be reopened for 16829 *every* snapfb snapshot, set the environment variable: 16830 SNAPFB_RAWFB_RESET=1 as well. 16831 16832 If you want x11vnc to dynamically transform a 24bpp 16833 rawfb to 32bpp (note that this will be slower) also 16834 supply the -24to32 option. This would be useful for, 16835 say, a video camera that delivers the pixel data as 16836 24bpp packed RGB. This is the default under "video" 16837 mode if the bpp is 24. 16838 16839 Normally the bits per pixel, B, is 8, 16, or 32 (or 16840 rarely 24), however there is also some support for 16841 B < 8 (e.g. old graphics displays 4 bpp or 1 bpp). 16842 In this case you certainly must supply the masks as 16843 well: WxHxB:R/G/B. The pixels will be padded out to 16844 8 bpp using depth 8 truecolor. The scheme currently 16845 does not work with snap fb (ask if interested.) B=1 16846 monochrome example: file:/dev/urandom@128x128x1:1/1/1 16847 Some other like this are 128x128x2:3/3/3 128x128x4:7/7/7 16848 16849 For B < 8 framebuffers you can also set the env. var 16850 RAWFB_CGA=1 to try a CGA mapping for B=4 (e.g. linux 16851 vga16fb driver.) Note with low bpp and/or resolution 16852 VGA and VGA16 modes on the Linux console one's attempt 16853 to export them via x11vnc can often be thwarted due to 16854 special color palettes, pixel packings, and even video 16855 painting buffering. OTOH, often experimenting with the 16856 RGB masks can yield something recognizable. 16857 16858 VIDEO4LINUX: on Linux some attempt is made to handle 16859 video devices (webcams or TV tuners) automatically. 16860 The idea is the WxHxB will be extracted from the 16861 device itself. So if you do not supply "@WxHxB... 16862 parameters x11vnc will try to determine them. It first 16863 tries the v4l API if that support has been compiled in. 16864 Otherwise it will run the v4l-info(1) external program 16865 if it is available. 16866 16867 The simplest examples are "-rawfb video" and "-rawfb 16868 video1" which imply the device file /dev/video and 16869 /dev/video1, respectively. You can also supply the 16870 /dev if you like, e.g. "-rawfb /dev/video0" 16871 16872 Since the video capture device framebuffer usually 16873 changes continuously (e.g. brightness fluctuations), 16874 you may want to use the -wait, -slow_fb, or -defer 16875 options to lower the "framerate" to cut down on 16876 network VNC traffic. 16877 16878 A more sophisticated video device scheme allows 16879 initializing the device's settings using: 16880 16881 -rawfb video:<settings> 16882 16883 The prefix could also be, as above, e.g. "video1:" to 16884 specify the device file. The v4l API must be available 16885 for this to work. Otherwise, you will need to try 16886 to initialize the device with an external program, 16887 e.g. xawtv, spcaview, and hope they persist when x11vnc 16888 re-opens the device. 16889 16890 <settings> is a comma separated list of key=value pairs. 16891 The device's brightness, color, contrast, and hue can 16892 be set to percentages, e.g. br=80,co=50,cn=44,hu=60. 16893 16894 The device filename can be set too if needed (if it 16895 does not start with "video"), e.g. fn=/dev/qcam. 16896 16897 The width, height and bpp of the framebuffer can be 16898 set via, e.g., w=160,h=120,bpp=16. 16899 16900 Related to the bpp above, the pixel format can be set 16901 via the fmt=XXX, where XXX can be one of: GREY, HI240, 16902 RGB555, RGB565, RGB24, and RGB32 (with bpp 8, 8, 16, 16, 16903 24, and 32 respectively). See http://www.linuxtv.org 16904 for more info (V4L api). 16905 16906 For TV/rf tuner cards one can set the tuning mode 16907 via tun=XXX where XXX can be one of PAL, NTSC, SECAM, 16908 or AUTO. 16909 16910 One can switch the input channel by the inp=XXX setting, 16911 where XXX is the name of the input channel (Television, 16912 Composite1, S-Video, etc). Use the name that is in the 16913 information about the device that is printed at startup. 16914 16915 For input channels with tuners (e.g. Television) one 16916 can change which station is selected by the sta=XXX 16917 setting. XXX is the station number. Currently only 16918 the ntsc-cable-us (US cable) channels are built into 16919 x11vnc. See the -freqtab option below to supply one 16920 from xawtv. If XXX is greater than 500, then it is 16921 interpreted as a raw frequency in KHz. 16922 16923 Example: 16924 16925 -rawfb video:br=80,w=320,h=240,fmt=RGB32,tun=NTSC,sta=47 16926 16927 one might need to add inp=Television too for the input 16928 channel to be TV if the card doesn't come up by default 16929 in that one. 16930 16931 Note that not all video capture devices will support 16932 all of the above settings. 16933 16934 See the -pipeinput VID option below for a way to control 16935 the settings through the VNC Viewer via keystrokes. 16936 As a shortcut, if the string begins "Video.." instead 16937 of "video.." then -pipeinput VID is implied. 16938 16939 As above, if you specify a "@WxHxB..." after the 16940 <settings> string they are used verbatim: the device 16941 is not queried for the current values. Otherwise the 16942 device will be queried. 16943 16944 LINUX CONSOLE: The following describes some ways to 16945 view and possibly interact with the Linux text/graphics 16946 console (i.e. not X11 XFree86/Xorg) 16947 16948 Note: If the LibVNCServer LinuxVNC program is on your 16949 system you may want to use that instead of the following 16950 method because it will be faster and more accurate 16951 for the Linux text console and includes mouse support. 16952 There is, however, the basic LinuxVNC functionality in 16953 x11vnc if you replace "console" with "vt" in the 16954 examples below. 16955 16956 If the rawfb string begins with "console" the 16957 framebuffer device /dev/fb0 is opened and /dev/tty0 is 16958 opened too. The latter is used to inject keystrokes 16959 (not all are supported, but the basic ones are). 16960 You will need to be root to inject keystrokes, but 16961 not necessarily to open /dev/fb0. /dev/tty0 refers to 16962 the active VT, to indicate one explicitly, use, e.g., 16963 "console2" for /dev/tty2, etc. by indicating the 16964 specific VT number. 16965 16966 For the Linux framebuffer device, /dev/fb0, (fb1, 16967 etc) to be enabled the appropriate kernel drivers must 16968 be loaded. E.g. vesafb or vga16fb and also by setting 16969 the boot parameter vga=0x301 (or 0x314, 0x317, etc.) 16970 (The vga=... method is the preferred way; set your 16971 machines up that way.) Otherwise there will be a 16972 'No such device' error. You can also load a Linux 16973 framebuffer driver specific to your make of video card 16974 for more functionality. Once the machine is booted one 16975 can often 'modprobe' the fb driver as root to obtain 16976 a framebuffer device. 16977 16978 If you cannot get /dev/fb0 working on Linux, try 16979 using the LinuxVNC emulation mode by "-rawfb vtN" 16980 where N = 1, ... 6 is the Linux Virtual Terminal (aka 16981 virtual console) you wish to view, e.g. "-rawfb vt2". 16982 Unlike /dev/fb mode, it need not be the active Virtual 16983 Terminal. Note that this mode can only show text and 16984 not graphics. x11vnc polls the text in /dev/vcsaN 16985 16986 Set the env. var. RAWFB_VCSA_BW=1 to disable colors in 16987 the "vtN" mode (i.e. black and white only.) If you 16988 do not prefer the default 16bpp set RAWFB_VCSA_BPP to 16989 8 or 32. If you need to tweak the rawfb parameters by 16990 using the 'console_guess' string printed at startup, 16991 be sure to indicate the snap: method. 16992 16993 uinput: If the Linux version appears to be 2.6 16994 or later and the "uinput" module appears to be 16995 present (modprobe uinput), then the uinput method 16996 will be used instead of /dev/ttyN. uinput allows 16997 insertion of BOTH keystrokes and mouse input and so it 16998 preferred when accessing graphical (e.g. QT-embedded) 16999 linux console apps. It also provides more accurate 17000 keystroke insertion. See -pipeinput UINPUT below for 17001 more information on this mode; you will have to use 17002 -pipeinput if you want to tweak any UINPUT parameters. 17003 You may also want to also use the -nodragging and 17004 -cursor none options. Use "console0", etc or 17005 -pipeinput CONSOLE to force the /dev/ttyN method. 17006 17007 Note you can change the Linux VT remotely using the 17008 chvt(1) command to make the one you want be the active 17009 one (e.g. 'chvt 3'). Sometimes switching out and back 17010 corrects the framebuffer's graphics state. For the 17011 "-rawfb vtN" mode there is no need to switch the VT's. 17012 17013 To skip input injecting entirely use "consolex" 17014 or "vtx". 17015 17016 The string "/dev/fb0" (1, etc.) can be used instead 17017 of "console". This can be used to specify a different 17018 framebuffer device, e.g. /dev/fb1. As a shortcut the 17019 "/dev/" can be dropped. If the name is something 17020 nonstandard, use "console:/dev/foofb" 17021 17022 If you do not want x11vnc to guess the framebuffer's 17023 WxHxB and masks automatically (sometimes the kernel 17024 gives incorrect information), specify them with a @WxHxB 17025 (and optional :R/G/B masks) at the end of the string. 17026 17027 Examples: 17028 -rawfb console 17029 -rawfb /dev/fb0 (same) 17030 -rawfb console3 (force /dev/tty3) 17031 -rawfb consolex (no keystrokes or mouse) 17032 -rawfb console:/dev/nonstd 17033 -rawfb console -pipeinput UINPUT:accel=4.0 17034 -rawfb vt3 (/dev/tty3 w/o /dev/fb0) 17035 17036 VNC HOST: if the -rawfb string is of the form 17037 "vnc:host:N" then the VNC display "N" on the remote 17038 VNC server "host" is connected to (i.e. x11vnc acts as 17039 a VNC client itself) and that framebuffer is exported. 17040 17041 This mode is really only of use if you are trying 17042 to improve performance in the case of many (e.g. > 17043 10) simultaneous VNC viewers, and you try a divide 17044 and conquer scheme to reduce bandwidth and improve 17045 responsiveness. (However, another user found this mode 17046 useful to export a demo display through a slow link: 17047 then multiple demo viewers connected to the reflecting 17048 x11vnc on the fast side of the link, and so avoided 17049 all of the demo viewers going through the slow link.) 17050 17051 For example, if there will be 64 simultaneous VNC 17052 viewers this can lead to a lot of redundant VNC traffic 17053 to and from the server host:N, extra CPU usage, 17054 and all viewers response can be reduced by having 17055 to wait for writes to the slowest client to finish. 17056 However, if you set up 8 reflectors/repeaters started 17057 with option -rawfb vnc:host:N, then there are only 17058 8 connections to host:N. Each repeater then handles 17059 8 vnc viewer connections thereby spreading the load 17060 around. In classroom broadcast usage, try to put the 17061 repeaters on different switches. This mode is the same 17062 as -reflect host:N. Replace "host:N" by "listen" 17063 or "listen:port" for a reverse connection. 17064 17065 Overall performance will not be as good as a single 17066 direct connection because, among other things, 17067 there is an additional level of framebuffer polling 17068 and pointer motion can still induce many changes per 17069 second that must be propagated. Tip: if the remote VNC 17070 is x11vnc doing wireframing, or an X display that does 17071 wireframing that gives much better response than opaque 17072 window dragging. Consider the -nodragging option if 17073 the problem is severe. 17074 17075 The env. var. X11VNC_REFLECT_PASSWORD can be set to 17076 the password needed to log into the vnc host server, or 17077 to "file:path_to_file" to indicate a file containing 17078 the password as its first line. 17079 17080 To set the pixel format that x11vnc requests as a VNC 17081 CLIENT set the env. vars: X11VNC_REFLECT_bitsPerSample 17082 X11VNC_REFLECT_samplesPerPixel, and 17083 X11VNC_REFLECT_bytesPerPixel; the defaults are 8, 3, 4. 17084 2, 3, 1 would give a low color mode. See the function 17085 rfbGetClient() in libvncclient for more info. 17086 17087 The VNC HOST mode implies -shared. Use -noshared as 17088 a subsequent cmdline option to disable sharing. 17089 17090 -freqtab file For use with "-rawfb video" for TV tuner devices to 17091 specify station frequencies. Instead of using the built 17092 in ntsc-cable-us mapping of station number to frequency, 17093 use the data in file. For stations that are not 17094 numeric, e.g. SE20, they are placed above the highest 17095 numbered station in the order they are found. Example: 17096 "-freqtab /usr/X11R6/share/xawtv/europe-west.list" 17097 You can make your own freqtab by copying the xawtv 17098 format. 17099 17100 -pipeinput cmd This option lets you supply an external command in 17101 "cmd" that x11vnc will pipe all of the user input 17102 events to in a simple format. In -pipeinput mode by 17103 default x11vnc will not process any of the user input 17104 events. If you prefix "cmd" with "tee:" it will 17105 both send them to the pipe command and process them. 17106 For a description of the format run "-pipeinput 17107 tee:/bin/cat". Another prefix is "reopen" which 17108 means to reopen pipe if it exits. Separate multiple 17109 prefixes with commas. 17110 17111 In combination with -rawfb one might be able to 17112 do amusing things (e.g. control non-X devices). 17113 To facilitate this, if -rawfb is in effect then the 17114 value is stored in X11VNC_RAWFB_STR for the pipe command 17115 to use if it wants. Do 'env | grep X11VNC' for more. 17116 17117 Built-in pipeinput modes (no external program required): 17118 17119 If cmd is "VID" and you are using the -rawfb for a 17120 video capture device, then an internal list of keyboard 17121 mappings is used to set parameters of the video. 17122 The mappings are: 17123 17124 "B" and "b" adjust the brightness up and down. 17125 "H" and "h" adjust the hue. 17126 "C" and "c" adjust the colour. 17127 "N" and "n" adjust the contrast. 17128 "S" and "s" adjust the size of the capture screen. 17129 "I" and "i" cycle through input channels. 17130 Up and Down arrows adjust the station (if a tuner) 17131 F1, F2, ..., F6 will switch the video capture pixel 17132 format to HI240, RGB565, RGB24, RGB32, RGB555, and 17133 GREY respectively. See -rawfb video for details. 17134 17135 If cmd is "CONSOLE" or "CONSOLEn" where n 17136 is a Linux console number, then the linux console 17137 keystroke insertion to /dev/ttyN (see -rawfb console) 17138 is performed. 17139 17140 If cmd begins with "UINPUT" then the Linux uinput 17141 module is used to insert both keystroke and mouse events 17142 to the Linux console (see -rawfb above). This usually 17143 is the /dev/input/uinput device file (you may need to 17144 create it with "mknod /dev/input/uinput c 10 223" 17145 and insert the module with "modprobe uinput". 17146 17147 The UINPUT mode currently only does US keyboards (a 17148 scan code option may be added), and not all keysyms 17149 are supported. But it is probably more accurate than 17150 the "CONSOLE" method. 17151 17152 You may want to use the options -cursor none and 17153 -nodragging in this mode. 17154 17155 Additional tuning options may be supplied via: 17156 UINPUT:opt1,opt2,... (a comma separated list). If an 17157 option begins with "/" it is taken as the uinput 17158 device file. 17159 17160 Which uinput is injected can be controlled by an option 17161 string made of the characters "K", "M", and "B" 17162 (see the -input option), e.g. "KM" allows keystroke 17163 and motion but not button clicks. 17164 17165 A UINPUT option of the form: accel=f, or accel=fx+fy 17166 sets the mouse motion "acceleration". This is used 17167 to correct raw mouse relative motion into how much the 17168 application cursor moves (x11vnc has no control over, 17169 or knowledge of how the windowing application interprets 17170 the raw mouse motions). Typically the acceleration 17171 for an X display is 2 (see xset "m" option). "f" 17172 is a floating point number, e.g. 3.0. Use "fx+fy" 17173 if you need to supply different corrections for x and y. 17174 17175 Note: the default acceleration is 2.0 since it seems 17176 both X and qt-embedded often (but not always) use 17177 this value. 17178 17179 Even with a correct accel setting the mouse position 17180 will get out of sync (probably due to a mouse 17181 "threshold" setting where the acceleration doe not 17182 apply, set xset(1)). The option reset=N sets the 17183 number of ms (default 150) after which the cursor is 17184 attempted to be reset (by forcing the mouse to (0, 17185 0) via small increments and then back out to (x, y) 17186 in 1 jump), This correction seems to be needed but can 17187 cause jerkiness or unexpected behavior with menus, etc. 17188 Use reset=0 to disable. 17189 17190 If you set the env. var X11VNC_UINPUT_THRESHOLDS then 17191 the thresh=n mode will be enabled. It is currently 17192 not working well. If |dx| <= thresh and |dy| < thresh 17193 no acceleration is applied. Use "thresh=+n" |dx| + 17194 |dy| < thresh to be used instead (X11?) 17195 17196 Example: 17197 -pipeinput UINPUT:accel=4.0 -cursor none 17198 17199 If the uinput device has an absolute pointer (as opposed 17200 to a normal mouse that is a relative pointer) you can 17201 specify the option "abs". Note that a touchpad 17202 on a laptop is an absolute device to some degree. 17203 This (usually) avoids all the problems with mouse 17204 acceleration. If x11vnc has trouble deducing the 17205 size of the device, use "abs=WxH". Furthermore, 17206 if the device is a touchscreen (assumed to have an 17207 absolute pointer) use "touch" or "touch=WxH". 17208 For touchscreens, when a mouse button is pressed, 17209 a pressure increase is injected, and when the button 17210 is released a pressure of zero is injected. 17211 17212 If touch has been set, use "touch_always=1" to 17213 indicate whenever the mouse moves with no button 17214 pressed, a touch event of zero pressure should be 17215 sent anyway. Also use "btn_touch=1" to indicate a 17216 BTN_TOUCH keystroke press or release should be sent 17217 instead of a pressure change. Set "dragskip=n" to 17218 skip n dragged mouse touches (with pressure applied) 17219 before injecting one. To indicate the pressure that 17220 should be sent when there is a button click for a 17221 touchscreen device, specify pressure=n, e.g. n=5. The 17222 default is n=1. 17223 17224 If a touch screen is being used ("touch" above) 17225 and it is having its input processed by tslib, you can 17226 specify the tslib calibration file via tslib_cal=<file>. 17227 For example, tslib_cal=/etc/pointercal. To get accurate 17228 or even usable positioning this is required when tslib 17229 is in use. 17230 17231 The Linux uinput mechanism can be bypassed and one can 17232 write input events DIRECTLY to the devices instead. 17233 To do this, specify one or more of the following 17234 for the input classes: direct_rel=<device> 17235 direct_abs=<device> direct_btn=<device> or 17236 direct_key=<device>. The <device> file is usually 17237 something like /dev/input/event1 but you can specify 17238 any device file or pipe. You must specify each one 17239 of the above classes even if they correspond to the 17240 same device file (rel/abs and btn are often the same.) 17241 Look at the file /proc/bus/input/devices to get an idea 17242 what is available and the device filenames. Note: 17243 The /dev/input/mouse* devices do not seem to work, 17244 use the corresponding /dev/input/event* file instead. 17245 Any input class not directly specified as above will be 17246 handled via the uinput mechanism. To disable creating a 17247 uinput device (and thereby discarding unhandled input), 17248 specify "nouinput". 17249 17250 Examples: 17251 17252 -pipeinput UINPUT:direct_abs=/dev/input/event1 17253 17254 this was used on a qtmoko Neo freerunner (armel): 17255 17256 -pipeinput UINPUT:touch,tslib_cal=/etc/pointercal, 17257 direct_abs=/dev/input/event1,nouinput,dragskip=4 17258 17259 (where the long line has been split into two.) 17260 17261 You can set the env. var X11VNC_UINPUT_DEBUG=1 or higher 17262 to get debugging output for UINPUT mode. 17263 17264 -macnodim For the native MacOSX server, disable dimming. 17265 -macnosleep For the native MacOSX server, disable display sleep. 17266 -macnosaver For the native MacOSX server, disable screensaver. 17267 -macnowait For the native MacOSX server, do not wait for the 17268 user to switch back to his display. 17269 -macwheel n For the native MacOSX server, set the mouse wheel 17270 speed to n (default 5). 17271 -macnoswap For the native MacOSX server, do not swap mouse 17272 buttons 2 and 3. 17273 -macnoresize For the native MacOSX server, do not resize or reset 17274 the framebuffer even if it is detected that the screen 17275 resolution or depth has changed. 17276 -maciconanim n For the native MacOSX server, set n to the number 17277 of milliseconds that the window iconify/deiconify 17278 animation takes. In -ncache mode this value will be 17279 used to skip the animation if possible. (default 400) 17280 -macmenu For the native MacOSX server, in -ncache client-side 17281 caching mode, try to cache pull down menus (not perfect 17282 because they have animated fades, etc.) 17283 -macuskbd For the native MacOSX server, use the original 17284 keystroke insertion code based on a US keyboard. 17285 -macnoopengl For the native MacOSX server, do not use OpenGL for 17286 screen capture, but rather use the original, deprecated 17287 raw memory access method: addr = CGDisplayBaseAddress(). 17288 -macnorawfb For the native MacOSX server, disable the raw memory 17289 address screen capture method. 17290 17291 MACOSX NOTE: There are some deprecated MacOSX interfaces 17292 to inject keyboard and mouse events and the raw memory 17293 access method is deprecated as well (however, OpenGL 17294 will be preferred if available because it is faster.) 17295 One can force not using any deprecated interfaces at 17296 compile time by setting -DX11VNC_MACOSX_NO_DEPRECATED=1 17297 in CPPFLAGS. Or to turn them off one by one: 17298 -DX11VNC_MACOSX_NO_DEPRECATED_LOCALEVENTS=1, 17299 -DX11VNC_MACOSX_NO_DEPRECATED_POSTEVENTS=1 or 17300 -DX11VNC_MACOSX_NO_DEPRECATED_FRAMEBUFFER=1 17301 At run time, for testing and workarounds, one can 17302 disable them by using: 17303 -env X11VNC_MACOSX_NO_DEPRECATED=1 17304 -env X11VNC_MACOSX_NO_DEPRECATED_LOCALEVENTS=1 17305 -env X11VNC_MACOSX_NO_DEPRECATED_POSTEVENTS=1 or 17306 -env X11VNC_MACOSX_NO_DEPRECATED_FRAMEBUFFER=1 17307 Note: When doing either of these for the mouse input 17308 not everything works currently, e.g. double clicks and 17309 wireframing. Also, screen resolution and pixel depth 17310 changes will not be automatically detected unless the 17311 deprecated framebuffer interfaces are allowed. 17312 17313 Conversely, if you are compiling on an 17314 older machine that does not have some of 17315 the newer interfaces, you may need to specify 17316 -DX11VNC_MACOSX_NO_CGEVENTCREATESCROLLWHEELEVENT 17317 -DX11VNC_MACOSX_NO_CGEVENTCREATEMOUSEEVENT or 17318 -DX11VNC_MACOSX_NO_CGEVENTCREATEKEYBOARDEVENT. Use 17319 -DX11VNC_MACOSX_USE_GETMAINDEVICE to regain the very 17320 old QuickDraw GetMainDevice() interface (rare...) 17321 17322 -gui [gui-opts] Start up a simple tcl/tk gui based on the remote 17323 control options -remote/-query described below. 17324 Requires the "wish" program to be installed on the 17325 machine. "gui-opts" is not required: the default 17326 is to start up both the full gui and x11vnc with the 17327 gui showing up on the X display in the environment 17328 variable DISPLAY. 17329 17330 "gui-opts" can be a comma separated list of items. 17331 Currently there are these types of items: 1) a gui 17332 mode, a 2) gui "simplicity", 3) the X display the 17333 gui should display on, 4) a "tray" or "icon" mode, 17334 and 5) a gui geometry. 17335 17336 1) The gui mode can be "start", "conn", or "wait" 17337 "start" is the default mode above and is not required. 17338 "conn" means do not automatically start up x11vnc, 17339 but instead just try to connect to an existing x11vnc 17340 process. "wait" means just start the gui and nothing 17341 else (you will later instruct the gui to start x11vnc 17342 or connect to an existing one.) 17343 17344 2) The gui simplicity is off by default (a power-user 17345 gui with all options is presented) To start with 17346 something less daunting supply the string "simple" 17347 ("ez" is an alias for this). Once the gui is 17348 started you can toggle between the two with "Misc -> 17349 simple_gui". 17350 17351 3) Note the possible confusion regarding the potentially 17352 two different X displays: x11vnc polls one, but you 17353 may want the gui to appear on another. For example, if 17354 you ssh in and x11vnc is not running yet you may want 17355 the gui to come back to you via your ssh redirected X 17356 display (e.g. localhost:10). 17357 17358 If you do not specify a gui X display in "gui-opts" 17359 then the DISPLAY environment variable and -display 17360 option are tried (in that order). Regarding the x11vnc 17361 X display the gui will try to communication with, it 17362 first tries -display and then DISPLAY. For example, 17363 "x11vnc -display :0 -gui otherhost:0", will remote 17364 control an x11vnc polling :0 and display the gui on 17365 otherhost:0 The "tray/icon" mode below reverses this 17366 preference, preferring to display on the x11vnc display. 17367 17368 4) When "tray" or "icon" is specified, the gui 17369 presents itself as a small icon with behavior typical 17370 of a "system tray" or "dock applet". The color 17371 of the icon indicates status (connected clients) and 17372 there is also a balloon status. Clicking on the icon 17373 gives a menu from which properties, etc, can be set and 17374 the full gui is available under "Advanced". To be 17375 fully functional, the gui mode should be "start" 17376 (the default). 17377 17378 Note that tray or icon mode will imply the -forever 17379 x11vnc option (if the x11vnc server is started along 17380 with the gui) unless -connect or -connect_or_exit has 17381 been specified. So x11vnc (and the tray/icon gui) 17382 will wait for more connections after the first client 17383 disconnects. If you want only one viewer connection 17384 include the -once option. 17385 17386 For "icon" the gui just a small standalone window. 17387 For "tray" it will attempt to embed itself in the 17388 "system tray" if possible. If "=setpass" is appended the 17389 n 17390 at startup the X11 user will be prompted to set the 17391 VNC session password. If =<hexnumber> is appended 17392 that icon will attempt to embed itself in the window 17393 given by hexnumber. Use =noadvanced to disable the 17394 full gui. (To supply more than one, use "+" sign). 17395 E.g. -gui tray=setpass and -gui icon=0x3600028 17396 17397 Other modes: "full", the default and need not be 17398 specified. "-gui none", do not show a gui, useful 17399 to override a ~/.x11vncrc setting, etc. 17400 17401 5) When "geom=+X+Y" is specified, that geometry 17402 is passed to the gui toplevel. This is the icon in 17403 icon/tray mode, or the full gui otherwise. You can 17404 also specify width and height, i.e. WxH+X+Y, but it 17405 is not recommended. In "tray" mode the geometry is 17406 ignored unless the system tray manager does not seem 17407 to be running. One could imagine using something like 17408 "-gui tray,geom=+4000+4000" with a display manager 17409 to keep the gui invisible until someone logs in... 17410 17411 More icon tricks, "icon=minimal" gives an icon just 17412 with the VNC display number. You can also set the font 17413 with "iconfont=...". The following could be useful: 17414 "-gui icon=minimal,iconfont=5x8,geom=24x10+0-0" 17415 17416 General examples of the -gui option: "x11vnc -gui", 17417 "x11vnc -gui ez" "x11vnc -gui localhost:10", 17418 "x11vnc -gui conn,host:0", "x11vnc -gui tray,ez" 17419 "x11vnc -gui tray=setpass" 17420 17421 If you do not intend to start x11vnc from the gui 17422 (i.e. just remote control an existing one), then the 17423 gui process can run on a different machine from the 17424 x11vnc server as long as X permissions, etc. permit 17425 communication between the two. 17426 17427 FONTS: On some systems the tk fonts can be too small, 17428 jagged, or otherwise unreadable. There are 4 env vars 17429 you can set to be the tk font you prefer: 17430 17431 X11VNC_FONT_BOLD main font for menus and buttons. 17432 X11VNC_FONT_FIXED font for fixed width text. 17433 17434 X11VNC_FONT_BOLD_SMALL tray icon font. 17435 X11VNC_FONT_REG_SMALL tray icon menu font. 17436 17437 The last two only apply for the tray icon mode. 17438 17439 Here are some examples: 17440 17441 -env X11VNC_FONT_BOLD='Helvetica -16 bold' 17442 -env X11VNC_FONT_FIXED='Courier -14' 17443 -env X11VNC_FONT_REG_SMALL='Helvetica -12' 17444 17445 You can put the lines like the above (without the 17446 quotes) in your ~/.x11vncrc file to avoid having to 17447 specify them on the x11vnc command line. 17448 17449 -remote command Remotely control some aspects of an already running 17450 x11vnc server. "-R" and "-r" are aliases for 17451 "-remote". After the remote control command is 17452 sent to the running server the 'x11vnc -remote ...' 17453 x11vnc command exits. You can often use the -query 17454 command (see below) to see if the x11vnc server 17455 processed your -remote command. 17456 17457 The default communication channel is that of X 17458 properties (specifically X11VNC_REMOTE), and so this 17459 command must be run with correct settings for DISPLAY 17460 and possibly XAUTHORITY to connect to the X server 17461 and set the property. Alternatively, use the -display 17462 and -auth options to set them to the correct values. 17463 The running server cannot use the -novncconnect option 17464 because that disables the communication channel. 17465 See below for alternate channels. 17466 17467 For example: 'x11vnc -remote stop' (which is the same as 17468 'x11vnc -R stop') will close down the x11vnc server. 17469 'x11vnc -R shared' will enable shared connections, and 17470 'x11vnc -R scale:3/4' will rescale the desktop. 17471 17472 To use a different name for the X11 property (e.g. to 17473 have separate communication channels for multiple 17474 x11vnc's on the same display) set the X11VNC_REMOTE 17475 environment variable to the string you want, for 17476 example: -env X11VNC_REMOTE=X11VNC_REMOTE_12345 17477 Both sides of the channel must use the same unique name. 17478 17479 To run a bunch of commands in a sequence use something 17480 like: x11vnc -R 'script:firstcmd;secondcmd;...' 17481 17482 Use x11vnc -R script:file=/path/to/file to read commands 17483 from a file (can be multi-line and use the comment '#' 17484 character in the normal way. The ';' separator must 17485 still be used to separate each command.) 17486 17487 To not try to contact another x11vnc process and instead 17488 just run the command (or query) directly, prefix the 17489 command with the string "DIRECT:" 17490 17491 The following -remote/-R commands are supported: 17492 17493 stop terminate the server, same as "quit" 17494 "exit" or "shutdown". 17495 ping see if the x11vnc server responds. 17496 return is: ans=ping:<display> 17497 ping:mystring as above, but use your own unique string 17498 . 17499 return is: ans=ping:mystring:<xdisplay> 17500 blacken try to push a black fb update to all 17501 clients (due to timings a client 17502 could miss it). Same as "zero", also 17503 "zero:x1,y1,x2,y2" for a rectangle. 17504 refresh send the entire fb to all clients. 17505 reset recreate the fb, polling memory, etc. 17506 id:windowid set -id window to "windowid". empty 17507 or "root" to go back to root window 17508 sid:windowid set -sid window to "windowid" 17509 id_cmd:cmd cmds: raise, lower, map, unmap, iconify, 17510 move:dXdY, resize:dWdH, geom:WxH+X+Y. dX 17511 dY, dW, and dH must have a leading "+" 17512 or "-" e.g.: move:-30+10 resize:+20+35 17513 also: wm_delete, wm_name:string and 17514 icon_name:string. Also id_cmd:win=N:cmd 17515 waitmapped wait until subwin is mapped. 17516 nowaitmapped do not wait until subwin is mapped. 17517 clip:WxH+X+Y set -clip mode to "WxH+X+Y" 17518 flashcmap enable -flashcmap mode. 17519 noflashcmap disable -flashcmap mode. 17520 shiftcmap:n set -shiftcmap to n. 17521 notruecolor enable -notruecolor mode. 17522 truecolor disable -notruecolor mode. 17523 overlay enable -overlay mode (if applicable). 17524 nooverlay disable -overlay mode. 17525 overlay_cursor in -overlay mode, enable cursor drawing. 17526 overlay_nocursor disable cursor drawing. same as 17527 nooverlay_cursor. 17528 8to24 enable -8to24 mode (if applicable). 17529 no8to24 disable -8to24 mode. 17530 8to24_opts:str set the -8to24 opts to "str". 17531 24to32 enable -24to32 mode (if applicable). 17532 no24to32 disable -24to32 mode. 17533 visual:vis set -visual to "vis" 17534 scale:frac set -scale to "frac" 17535 scale_cursor:f set -scale_cursor to "f" 17536 viewonly enable -viewonly mode. 17537 noviewonly disable -viewonly mode. 17538 shared enable -shared mode. 17539 noshared disable -shared mode. 17540 forever enable -forever mode. 17541 noforever disable -forever mode. 17542 timeout:n reset -timeout to n, if there are 17543 currently no clients, exit unless one 17544 connects in the next n secs. 17545 tightfilexfer enable filetransfer for NEW clients. 17546 notightfilexfer disable filetransfer for NEW clients. 17547 ultrafilexfer enable filetransfer for clients. 17548 noultrafilexfer disable filetransfer for clients. 17549 rfbversion:n.m set -rfbversion for new clients. 17550 http enable http client connections. 17551 nohttp disable http client connections. 17552 deny deny any new connections, same as "lock" 17553 nodeny allow new connections, same as "unlock" 17554 avahi enable avahi service advertising. 17555 noavahi disable avahi service advertising. 17556 mdns enable avahi service advertising. 17557 nomdns disable avahi service advertising. 17558 zeroconf enable avahi service advertising. 17559 nozeroconf disable avahi service advertising. 17560 connect:host do reverse connection to host, "host" 17561 may be a comma separated list of hosts 17562 or host:ports. See -connect. Passwords 17563 required as with fwd connections. 17564 See X11VNC_REVERSE_CONNECTION_NO_AUTH=1 17565 disconnect:host disconnect any clients from "host" 17566 same as "close:host". Use host 17567 "all" to close all current clients. 17568 If you know the client internal hex ID, 17569 e.g. 0x3 (returned by "-query clients" 17570 and RFB_CLIENT_ID) you can use that too. 17571 proxy:host:port set reverse connection proxy (empty to 17572 disable). 17573 allowonce:host For the next connection only, allow 17574 connection from "host". In -ssl mode 17575 two connections are allowed (i.e. Fetch 17576 Cert) unless X11VNC_NO_SSL_ALLOW_TWICE=1 17577 allow:hostlist set -allow list to (comma separated) 17578 "hostlist". See -allow and -localhost. 17579 Do not use with -allow /path/to/file 17580 Use "+host" to add a single host, and 17581 use "-host" to delete a single host 17582 localhost enable -localhost mode 17583 nolocalhost disable -localhost mode 17584 listen:str set -listen to str, empty to disable. 17585 noipv6 enable -noipv6 mode. 17586 ipv6 disable -noipv6 mode. 17587 noipv4 enable -noipv4 mode. 17588 ipv4 disable -noipv4 mode. 17589 6 enable -6 IPv6 listening mode. 17590 no6 disable -6 IPv6 listening mode. 17591 lookup disable -nolookup mode. 17592 nolookup enable -nolookup mode. 17593 lookup disable -nolookup mode. 17594 input:str set -input to "str", empty to disable. 17595 grabkbd enable -grabkbd mode. 17596 nograbkbd disable -grabkbd mode. 17597 grabptr enable -grabptr mode. 17598 nograbptr disable -grabptr mode. 17599 grabalways enable -grabalways mode. 17600 nograbalways disable -grabalways mode. 17601 grablocal:n set -grablocal to n. 17602 client_input:str set the K, M, B -input on a per-client 17603 basis. select which client as for 17604 disconnect, e.g. client_input:host:MB 17605 or client_input:0x2:K 17606 accept:cmd set -accept "cmd" (empty to disable). 17607 afteraccept:cmd set -afteraccept (empty to disable). 17608 gone:cmd set -gone "cmd" (empty to disable). 17609 noshm enable -noshm mode. 17610 shm disable -noshm mode (i.e. use shm). 17611 flipbyteorder enable -flipbyteorder mode, you may need 17612 to set noshm for this to do something. 17613 noflipbyteorder disable -flipbyteorder mode. 17614 onetile enable -onetile mode. (you may need to 17615 set shm for this to do something) 17616 noonetile disable -onetile mode. 17617 solid enable -solid mode 17618 nosolid disable -solid mode. 17619 solid_color:color set -solid color (and apply it). 17620 blackout:str set -blackout "str" (empty to disable). 17621 See -blackout for the form of "str" 17622 (basically: WxH+X+Y,...) 17623 Use "+WxH+X+Y" to append a single 17624 rectangle use "-WxH+X+Y" to delete one 17625 xinerama enable -xinerama mode. (if applicable) 17626 noxinerama disable -xinerama mode. 17627 xtrap enable -xtrap input mode(if applicable) 17628 noxtrap disable -xtrap input mode. 17629 xrandr enable -xrandr mode. (if applicable) 17630 noxrandr disable -xrandr mode. 17631 xrandr_mode:mode set the -xrandr mode to "mode". 17632 rotate:mode set the -rotate mode to "mode". 17633 padgeom:WxH set -padgeom to WxH (empty to disable) 17634 If WxH is "force" or "do" the padded 17635 geometry fb is immediately applied. 17636 quiet enable -quiet mode. 17637 noquiet disable -quiet mode. 17638 modtweak enable -modtweak mode. 17639 nomodtweak enable -nomodtweak mode. 17640 xkb enable -xkb modtweak mode. 17641 noxkb disable -xkb modtweak mode. 17642 capslock enable -capslock mode. 17643 nocapslock disable -capslock mode. 17644 skip_lockkeys enable -skip_lockkeys mode. 17645 noskip_lockkeys disable -skip_lockkeys mode. 17646 skip_keycodes:str enable -xkb -skip_keycodes "str". 17647 sloppy_keys enable -sloppy_keys mode. 17648 nosloppy_keys disable -sloppy_keys mode. 17649 skip_dups enable -skip_dups mode. 17650 noskip_dups disable -skip_dups mode. 17651 add_keysyms enable -add_keysyms mode. 17652 noadd_keysyms stop adding keysyms. those added will 17653 still be removed at exit. 17654 clear_mods enable -clear_mods mode and clear them. 17655 noclear_mods disable -clear_mods mode. 17656 clear_keys enable -clear_keys mode and clear them. 17657 noclear_keys disable -clear_keys mode. 17658 clear_locks do the clear_locks action. 17659 clear_all do the clear_all action. 17660 keystate have x11vnc print current keystate. 17661 remap:str set -remap "str" (empty to disable). 17662 See -remap for the form of "str" 17663 (basically: key1-key2,key3-key4,...) 17664 Use "+key1-key2" to append a single 17665 keymapping, use "-key1-key2" to delete. 17666 norepeat enable -norepeat mode. 17667 repeat disable -norepeat mode. 17668 nofb enable -nofb mode. 17669 fb disable -nofb mode. 17670 bell enable bell (if supported). 17671 nobell disable bell. 17672 sendbell ring the bell now. 17673 nosel enable -nosel mode. 17674 sel disable -nosel mode. 17675 noprimary enable -noprimary mode. 17676 primary disable -noprimary mode. 17677 nosetprimary enable -nosetprimary mode. 17678 setprimary disable -nosetprimary mode. 17679 noclipboard enable -noclipboard mode. 17680 clipboard disable -noclipboard mode. 17681 nosetclipboard enable -nosetclipboard mode. 17682 setclipboard disable -nosetclipboard mode. 17683 seldir:str set -seldir to "str" 17684 resend_cutbuffer resend the most recent CUTBUFFER0 copy 17685 resend_clipboard resend the most recent CLIPBOARD copy 17686 resend_primary resend the most recent PRIMARY copy 17687 cursor:mode enable -cursor "mode". 17688 show_cursor enable showing a cursor. 17689 noshow_cursor disable showing a cursor. (same as 17690 "nocursor") 17691 cursor_drag enable cursor changes during drag. 17692 nocursor_drag disable cursor changes during drag. 17693 arrow:n set -arrow to alternate n. 17694 xfixes enable xfixes cursor shape mode. 17695 noxfixes disable xfixes cursor shape mode. 17696 alphacut:n set -alphacut to n. 17697 alphafrac:f set -alphafrac to f. 17698 alpharemove enable -alpharemove mode. 17699 noalpharemove disable -alpharemove mode. 17700 alphablend disable -noalphablend mode. 17701 noalphablend enable -noalphablend mode. 17702 cursorshape disable -nocursorshape mode. 17703 nocursorshape enable -nocursorshape mode. 17704 cursorpos disable -nocursorpos mode. 17705 nocursorpos enable -nocursorpos mode. 17706 xwarp enable -xwarppointer mode. 17707 noxwarp disable -xwarppointer mode. 17708 always_inject enable -always_inject mode. 17709 noalways_inject disable -always_inject mode. 17710 buttonmap:str set -buttonmap "str", empty to disable 17711 dragging disable -nodragging mode. 17712 nodragging enable -nodragging mode. 17713 ncache reenable -ncache mode. 17714 noncache disable -ncache mode. 17715 ncache_size:n set -ncache size to n. 17716 ncache_cr enable -ncache_cr mode. 17717 noncache_cr disable -ncache_cr mode. 17718 ncache_no_moveraise enable no_moveraise mode. 17719 noncache_no_moveraise disable no_moveraise mode. 17720 ncache_no_dtchange enable ncache_no_dtchange mode. 17721 noncache_no_dtchange disable ncache_no_dtchange mode. 17722 ncache_old_wm enable ncache_old_wm mode. 17723 noncache_old_wm disable ncache_old_wm mode. 17724 ncache_no_rootpixmap enable ncache_no_rootpixmap. 17725 noncache_no_rootpixmap disable ncache_no_rootpixmap. 17726 ncache_reset_rootpixmap recheck the root pixmap, ncrp 17727 ncache_keep_anims enable ncache_keep_anims. 17728 noncache_keep_anims disable ncache_keep_anims. 17729 ncache_pad:n set -ncache_pad to n. 17730 wireframe enable -wireframe mode. same as "wf" 17731 nowireframe disable -wireframe mode. same as "nowf" 17732 wireframe:str enable -wireframe mode string. 17733 wireframe_mode:str enable -wireframe mode string. 17734 wireframelocal enable wireframelocal. same as "wfl" 17735 nowireframe disable wireframelocal. same as "nowfl" 17736 wirecopyrect:str set -wirecopyrect string. same as "wcr: 17737 " 17738 scrollcopyrect:str set -scrollcopyrect string. same "scr 17739 " 17740 noscrollcopyrect disable -scrollcopyrect mode. "noscr" 17741 scr_area:n set -scr_area to n 17742 scr_skip:list set -scr_skip to "list" 17743 scr_inc:list set -scr_inc to "list" 17744 scr_keys:list set -scr_keys to "list" 17745 scr_term:list set -scr_term to "list" 17746 scr_keyrepeat:str set -scr_keyrepeat to "str" 17747 scr_parms:str set -scr_parms parameters. 17748 fixscreen:str set -fixscreen to "str". 17749 noxrecord disable all use of RECORD extension. 17750 xrecord enable use of RECORD extension. 17751 reset_record reset RECORD extension (if avail.) 17752 pointer_mode:n set -pointer_mode to n. same as "pm" 17753 input_skip:n set -input_skip to n. 17754 allinput enable use of -allinput mode. 17755 noallinput disable use of -allinput mode. 17756 input_eagerly enable use of -input_eagerly mode. 17757 noinput_eagerly disable use of -input_eagerly mode. 17758 ssltimeout:n set -ssltimeout to n. 17759 speeds:str set -speeds to str. 17760 wmdt:str set -wmdt to str. 17761 debug_pointer enable -debug_pointer, same as "dp" 17762 nodebug_pointer disable -debug_pointer, same as "nodp" 17763 debug_keyboard enable -debug_keyboard, same as "dk" 17764 nodebug_keyboard disable -debug_keyboard, same as "nodk" 17765 keycode:n inject keystroke 'keycode' (xmodmap -pk) 17766 keycode:n,down inject 'keycode' (down=0,1) 17767 keysym:str inject keystroke 'keysym' (number/name) 17768 keysym:str,down inject 'keysym' (down=0,1) 17769 ptr:x,y,mask inject pointer event x, y, button-mask 17770 fakebuttonevent:button,down direct XTestFakeButtonEvent. 17771 sleep:t sleep floating point time t. 17772 get_xprop:p get X property named 'p'. 17773 set_xprop:p:val set X property named 'p' to 'val'. 17774 p -> id=NNN:p for hex/dec window id. 17775 wininfo:id get info about X window id. use 'root' 17776 for root window, use +id for children. 17777 grab_state get state of pointer and keyboard grab. 17778 pointer_pos print XQueryPointer x,y cursor position. 17779 pointer_x print XQueryPointer x cursor position. 17780 pointer_y print XQueryPointer y cursor position. 17781 pointer_same print XQueryPointer ptr on same screen. 17782 pointer_root print XQueryPointer curr ptr rootwin. 17783 pointer_mask print XQueryPointer button and mods mask 17784 mouse_x print x11vnc's idea of cursor position. 17785 mouse_y print x11vnc's idea of cursor position. 17786 noop do nothing. 17787 defer:n set -defer to n ms,same as deferupdate:n 17788 wait:n set -wait to n ms. 17789 extra_fbur:n set -extra_fbur to n. 17790 wait_ui:f set -wait_ui factor to f. 17791 setdefer:n set -setdefer to -2,-1,0,1, or 2. 17792 wait_bog disable -nowait_bog mode. 17793 nowait_bog enable -nowait_bog mode. 17794 slow_fb:f set -slow_fb to f seconds. 17795 xrefresh:f set -xrefresh to f seconds. 17796 readtimeout:n set read timeout to n seconds. 17797 nap enable -nap mode. 17798 nonap disable -nap mode. 17799 sb:n set -sb to n s, same as screen_blank:n 17800 fbpm disable -nofbpm mode. 17801 nofbpm enable -nofbpm mode. 17802 dpms disable -nodpms mode. 17803 nodpms enable -nodpms mode. 17804 forcedpms enable -forcedpms mode. 17805 noforcedpms disable -forcedpms mode. 17806 clientdpms enable -clientdpms mode. 17807 noclientdpms disable -clientdpms mode. 17808 noserverdpms enable -noserverdpms mode. 17809 serverdpms disable -noserverdpms mode. 17810 noultraext enable -noultraext mode. 17811 ultraext disable -noultraext mode. 17812 chatwindow enable local chatwindow mode. 17813 nochatwindow disable local chatwindow mode. 17814 chaton begin chat using local window. 17815 chatoff end chat using local window. 17816 xdamage enable xdamage polling hints. 17817 noxdamage disable xdamage polling hints. 17818 xd_area:A set -xd_area max pixel area to "A" 17819 xd_mem:f set -xd_mem remembrance to "f" 17820 fs:frac set -fs fraction to "frac", e.g. 0.5 17821 gaps:n set -gaps to n. 17822 grow:n set -grow to n. 17823 fuzz:n set -fuzz to n. 17824 snapfb enable -snapfb mode. 17825 nosnapfb disable -snapfb mode. 17826 rawfb:str set -rawfb mode to "str". 17827 uinput_accel:f set uinput_accel to f. 17828 uinput_thresh:n set uinput_thresh to n. 17829 uinput_reset:n set uinput_reset to n ms. 17830 uinput_always:n set uinput_always to 1/0. 17831 progressive:n set LibVNCServer -progressive slice 17832 height parameter to n. 17833 desktop:str set -desktop name to str for new clients 17834 . 17835 rfbport:n set -rfbport to n. 17836 macnosaver enable -macnosaver mode. 17837 macsaver disable -macnosaver mode. 17838 macnowait enable -macnowait mode. 17839 macwait disable -macnowait mode. 17840 macwheel:n set -macwheel to n. 17841 macnoswap enable -macnoswap mouse button mode. 17842 macswap disable -macnoswap mouse button mode. 17843 macnoresize enable -macnoresize mode. 17844 macresize disable -macnoresize mode. 17845 maciconanim:n set -maciconanim to n. 17846 macmenu enable -macmenu mode. 17847 macnomenu disable -macmenu mode. 17848 macuskbd enable -macuskbd mode. 17849 macnouskbd disable -macuskbd mode. 17850 httpport:n set -httpport to n. 17851 httpdir:dir set -httpdir to dir (and enable http). 17852 enablehttpproxy enable -enablehttpproxy mode. 17853 noenablehttpproxy disable -enablehttpproxy mode. 17854 alwaysshared enable -alwaysshared mode. 17855 noalwaysshared disable -alwaysshared mode. 17856 (may interfere with other options) 17857 nevershared enable -nevershared mode. 17858 nonevershared disable -nevershared mode. 17859 (may interfere with other options) 17860 dontdisconnect enable -dontdisconnect mode. 17861 nodontdisconnect disable -dontdisconnect mode. 17862 (may interfere with other options) 17863 debug_xevents enable debugging X events. 17864 nodebug_xevents disable debugging X events. 17865 debug_xdamage enable debugging X DAMAGE mechanism. 17866 nodebug_xdamage disable debugging X DAMAGE mechanism. 17867 debug_wireframe enable debugging wireframe mechanism. 17868 nodebug_wireframe disable debugging wireframe mechanism. 17869 debug_scroll enable debugging scrollcopy mechanism. 17870 nodebug_scroll disable debugging scrollcopy mechanism. 17871 debug_tiles enable -debug_tiles 17872 nodebug_tiles disable -debug_tiles 17873 debug_grabs enable -debug_grabs 17874 nodebug_grabs disable -debug_grabs 17875 debug_sel enable -debug_sel 17876 nodebug_sel disable -debug_sel 17877 debug_ncache enable -debug_ncache 17878 nodebug_ncache disable -debug_ncache 17879 dbg enable -dbg crash shell 17880 nodbg disable -dbg crash shell 17881 17882 noremote disable the -remote command processing, 17883 it cannot be turned back on. 17884 17885 bcx_xattach:str This remote control command is for 17886 use with the BARCO xattach program or the x2x program. 17887 Both of these programs are for 'pointer and keyboard' 17888 sharing between separate X displays. In general the 17889 two displays are usually nearby, e.g. on the same desk, 17890 and this allows the user to share a single pointer and 17891 keyboard between them. The user moves the mouse to 17892 an edge and then the mouse pointer appears to 'jump' 17893 to the other display screen. Thus it emulates what a 17894 single X server would do for two screens (e.g. :0.0 and 17895 :0.1) The illusion of a single Xserver with multiple 17896 screens is achieved by forwarding events to the 2nd 17897 one via the XTEST extension. 17898 17899 What the x11vnc bcx_xattach command does is to perform 17900 some pointer movements to try to INDUCE xattach/x2x 17901 to 'jump' to the other display. In what follows the 17902 'master' display refers to the one that when it has 17903 'focus' it is basically doing nothing besides watching 17904 for the mouse to go over an edge. The 'slave' 17905 display refers to the one to which the mouse and 17906 keyboard is redirected to once an edge in the master 17907 has been crossed. Note that the x11vnc executing the 17908 bcx_xattach command MUST be the one connected to the 17909 *master* display. 17910 17911 Also note that when input is being redirected (via 17912 XTEST) from the master display to the slave display, 17913 the master display's pointer and keyboard are *grabbed* 17914 by xattach/x2x. x11vnc can use this info to verify that 17915 the master/slave mode change has taken place correctly. 17916 If you specify the "ifneeded" option (see below) 17917 and the initial grab state is that of the desired 17918 final state, then no pointer movements are injected 17919 and "DONE,GRAB_OK" is returned. 17920 17921 "str" must contain one of "up", "down", "left", 17922 or "right" to indicate the direction of the 'jump'. 17923 "str" must also contain one of "master_to_slave" 17924 or "slave_to_master" to indicate the type of mode 17925 change induced by the jump. Use "M2S" and "S2M" 17926 as shorter aliases. 17927 17928 "str" may be a "+" separated list of additional 17929 tuning options. The "shift=n" option indicates an 17930 offset shift position away from (0,0) (default 20). 17931 "final=x+y" specifies the final position of the cursor 17932 at the end of the normal move sequence; default 30+30. 17933 "extra_move=x+y" means to do one more pointer move 17934 after "final" to x+y. "dt=n" sets the sleep time 17935 in milliseconds between pointer moves (default: 40ms) 17936 "retry=n" specifies the maximum number of retries if 17937 the grab state change fails. "ifneeded" means to not 17938 apply the pointer movements if the initial grab state is 17939 that of the desired final state. "nograbcheck" means 17940 to not check if the grab state changed as expected and 17941 only apply the pointer movements (default is to check 17942 the grab states.) 17943 17944 If you do not specify "up", etc., to bcx_xattach 17945 nothing will be attempted and the command returns 17946 the string FAIL,NO_DIRECTION_SPECIFIED. If you do 17947 not specify "master_to_slave" or "M2S", etc., to 17948 bcx_xattach nothing will be attempted and the command 17949 returns the string FAIL,NO_MODE_CHANGE_SPECIFIED. 17950 17951 Otherwise, the returned string will contain "DONE". 17952 It will be "DONE,GRAB_OK" if the grab state changed 17953 as expected (or if "ifneeded" was supplied and 17954 the initial grab state was already the desired 17955 one.) If the initial grab state was incorrect, 17956 but the final grab state was correct then it is 17957 "DONE,GRAB_FAIL_INIT". If the initial grab state 17958 was correct, but the final grab state was incorrect 17959 then it is "DONE,GRAB_FAIL_FINAL". If both are 17960 incorrect it will be "DONE,GRAB_FAIL". Under grab 17961 failure the string will be followed by ":p1,k1-p2,k2" 17962 where p1,k1 indicates the initial pointer and keyboard 17963 grab states and p2,k2 the final ones. If GRAB_FAIL or 17964 GRAB_FAIL_FINAL occurs, the action will be retried up 17965 to 3 times; trying to reset the state and sleeping a 17966 bit between each try. Set retry=n to adjust the number 17967 of retries, zero to disable retries. 17968 17969 Examples: 17970 -R bcx_xattach:down+M2S 17971 -R bcx_xattach:up+S2M 17972 -R bcx_xattach:up+S2M+nograbcheck+dt=30 17973 -R bcx_xattach:down+M2S+extra_move=100+100 17974 17975 or use -Q instead of -R to retrieve the result text. 17976 17977 End of the bcx_xattach:str description. 17978 17979 The vncconnect(1) command from standard VNC 17980 distributions may also be used if string is prefixed 17981 with "cmd=" E.g. 'vncconnect cmd=stop'. Under some 17982 circumstances xprop(1) can used if it supports -set 17983 (see the FAQ). 17984 17985 If "-connect /path/to/file" has been supplied to the 17986 running x11vnc server then that file can be used as a 17987 communication channel (this is the only way to remote 17988 control one of many x11vnc's polling the same X display) 17989 Simply run: 'x11vnc -connect /path/to/file -remote ...' 17990 or you can directly write to the file via something 17991 like: "echo cmd=stop > /path/to/file", etc. 17992 17993 -query variable Like -remote, except just query the value of 17994 "variable". "-Q" is an alias for "-query". 17995 Multiple queries can be done by separating variables 17996 by commas, e.g. -query var1,var2. The results come 17997 back in the form ans=var1:value1,ans=var2:value2,... 17998 to the standard output. If a variable is read-only, 17999 it comes back with prefix "aro=" instead of "ans=". 18000 18001 Some -remote commands are pure actions that do not make 18002 sense as variables, e.g. "stop" or "disconnect", in 18003 these cases the value returned is "N/A". To direct a 18004 query straight to the X11VNC_REMOTE property or connect 18005 file use "qry=..." instead of "cmd=..." 18006 18007 ans= stop quit exit shutdown ping resend_cutbuffer 18008 resend_clipboard resend_primary blacken zero refresh 18009 reset close disconnect id_cmd id sid waitmapped 18010 nowaitmapped clip flashcmap noflashcmap shiftcmap 18011 truecolor notruecolor overlay nooverlay overlay_cursor 18012 overlay_yescursor nooverlay_nocursor nooverlay_cursor 18013 nooverlay_yescursor overlay_nocursor 8to24 no8to24 18014 8to24_opts 24to32 no24to32 visual scale scale_cursor 18015 viewonly noviewonly shared noshared forever noforever 18016 once timeout tightfilexfer notightfilexfer ultrafilexfer 18017 noultrafilexfer rfbversion deny lock nodeny unlock avahi 18018 mdns zeroconf noavahi nomdns nozeroconf connect proxy 18019 allowonce allow noipv6 ipv6 noipv4 ipv4 no6 6 localhost 18020 nolocalhost listen lookup nolookup accept afteraccept 18021 gone shm noshm flipbyteorder noflipbyteorder onetile 18022 noonetile solid_color solid nosolid blackout xinerama 18023 noxinerama xtrap noxtrap xrandr noxrandr xrandr_mode 18024 rotate padgeom quiet q noquiet modtweak nomodtweak xkb 18025 noxkb capslock nocapslock skip_lockkeys noskip_lockkeys 18026 skip_keycodes sloppy_keys nosloppy_keys skip_dups 18027 noskip_dups add_keysyms noadd_keysyms clear_mods 18028 noclear_mods clear_keys noclear_keys clear_all 18029 clear_locks keystate remap repeat norepeat fb nofb bell 18030 nobell sendbell sel nosel primary noprimary setprimary 18031 nosetprimary clipboard noclipboard setclipboard 18032 nosetclipboard seldir cursorshape nocursorshape 18033 cursorpos nocursorpos cursor_drag nocursor_drag cursor 18034 show_cursor noshow_cursor nocursor arrow xfixes noxfixes 18035 xdamage noxdamage xd_area xd_mem alphacut alphafrac 18036 alpharemove noalpharemove alphablend noalphablend 18037 xwarppointer xwarp noxwarppointer noxwarp always_inject 18038 noalways_inject buttonmap dragging nodragging ncache_cr 18039 noncache_cr ncache_no_moveraise noncache_no_moveraise 18040 ncache_no_dtchange noncache_no_dtchange 18041 ncache_no_rootpixmap noncache_no_rootpixmap 18042 ncache_reset_rootpixmap ncrp ncache_keep_anims 18043 noncache_keep_anims ncache_old_wm noncache_old_wm 18044 ncache_pad ncache noncache ncache_size debug_ncache 18045 nodebug_ncache wireframe_mode wireframe wf nowireframe 18046 nowf wireframelocal wfl nowireframelocal nowfl 18047 wirecopyrect wcr nowirecopyrect nowcr scr_area 18048 scr_skip scr_inc scr_keys scr_term scr_keyrepeat 18049 scr_parms scrollcopyrect scr noscrollcopyrect 18050 noscr fixscreen noxrecord xrecord reset_record 18051 pointer_mode pm input_skip allinput noallinput 18052 input_eagerly noinput_eagerly input grabkbd nograbkbd 18053 grabptr nograbptr grabalways nograbalways grablocal 18054 client_input ssltimeout speeds wmdt debug_pointer dp 18055 nodebug_pointer nodp debug_keyboard dk nodebug_keyboard 18056 nodk keycode keysym ptr fakebuttonevent sleep get_xprop 18057 set_xprop wininfo bcx_xattach deferupdate defer 18058 setdefer extra_fbur wait_ui wait_bog nowait_bog 18059 slow_fb xrefresh wait readtimeout nap nonap sb 18060 screen_blank fbpm nofbpm dpms nodpms clientdpms 18061 noclientdpms forcedpms noforcedpms noserverdpms 18062 serverdpms noultraext ultraext chatwindow nochatwindow 18063 chaton chatoff fs gaps grow fuzz snapfb nosnapfb 18064 rawfb uinput_accel uinput_thresh uinput_reset 18065 uinput_always progressive rfbport http nohttp httpport 18066 httpdir enablehttpproxy noenablehttpproxy alwaysshared 18067 noalwaysshared nevershared noalwaysshared dontdisconnect 18068 nodontdisconnect desktop debug_xevents nodebug_xevents 18069 debug_xevents debug_xdamage nodebug_xdamage 18070 debug_xdamage debug_wireframe nodebug_wireframe 18071 debug_wireframe debug_scroll nodebug_scroll debug_scroll 18072 debug_tiles dbt nodebug_tiles nodbt debug_tiles 18073 debug_grabs nodebug_grabs debug_sel nodebug_sel dbg 18074 nodbg macnosaver macsaver nomacnosaver macnowait macwait 18075 nomacnowait macwheel macnoswap macswap nomacnoswap 18076 macnoresize macresize nomacnoresize maciconanim macmenu 18077 macnomenu nomacmenu macuskbd nomacuskbd noremote 18078 18079 aro= noop display vncdisplay icon_mode autoport 18080 loop loopbg desktopname guess_desktop guess_dbus 18081 http_url auth xauth users rootshift clipshift scale_str 18082 scaled_x scaled_y scale_numer scale_denom scale_fac_x 18083 scale_fac_y scaling_blend scaling_nomult4 scaling_pad 18084 scaling_interpolate inetd privremote unsafe safer nocmds 18085 passwdfile unixpw unixpw_nis unixpw_list ssl ssl_pem 18086 sslverify stunnel stunnel_pem https httpsredir usepw 18087 using_shm logfile o flag rmflag rc norc h help V version 18088 lastmod bg sigpipe threads readrate netrate netlatency 18089 pipeinput clients client_count pid ext_xtest ext_xtrap 18090 ext_xrecord ext_xkb ext_xshm ext_xinerama ext_overlay 18091 ext_xfixes ext_xdamage ext_xrandr rootwin num_buttons 18092 button_mask mouse_x mouse_y grab_state pointer_pos 18093 pointer_x pointer_y pointer_same pointer_root 18094 pointer_mask bpp depth indexed_color dpy_x dpy_y wdpy_x 18095 wdpy_y off_x off_y cdpy_x cdpy_y coff_x coff_y rfbauth 18096 passwd viewpasswd 18097 18098 -QD variable Just like -query variable, but returns the default 18099 value for that parameter (no running x11vnc server 18100 is consulted) 18101 18102 -sync By default -remote commands are run asynchronously, that 18103 is, the request is posted and the program immediately 18104 exits. Use -sync to have the program wait for an 18105 acknowledgement from the x11vnc server that command was 18106 processed (somehow). On the other hand -query requests 18107 are always processed synchronously because they have 18108 to wait for the answer. 18109 18110 Also note that if both -remote and -query requests are 18111 supplied on the command line, the -remote is processed 18112 first (synchronously: no need for -sync), and then 18113 the -query request is processed in the normal way. 18114 This allows for a reliable way to see if the -remote 18115 command was processed by querying for any new settings. 18116 Note however that there is timeout of a few seconds 18117 (see the next paragraph) so if the x11vnc takes longer 18118 than that to process the requests the requester will 18119 think that a failure has taken place. 18120 18121 The default is to wait 3.5 seconds. Or if cmd=stop 18122 only 1.0 seconds. If cmd matches 'script:' then it 18123 will wait up to 10.0 seconds. Set X11VNC_SYNC_TIMEOUT 18124 to the number of seconds you want it to wait. 18125 18126 -query_retries str If a query fails to get a response from an x11vnc 18127 server, retry up to n times. "str" is specified as 18128 n[:t][/match] Optionally the delay between tries may 18129 be specified by "t" a floating point time (default 18130 0.5 seconds.) Note: the response is not checked for 18131 validity or whether it corresponds to the query sent. 18132 The query "ping:mystring" may be used to help uniquely 18133 identify the query. Optionally, a matching string after 18134 a "/" will be used to check the result text. Up to 18135 n retries will take place until the matching string is 18136 found in the output text. If the match string is never 18137 found the program's exit code is 1; if the match is 18138 found it exits with 0. Note that there may be stdout 18139 printed for each retry (i.e. multiple lines printed 18140 out to stdout.) 18141 Example: -query_retries 4:1.5/grab_state 18142 18143 -remote_prefix str Enable a remote-control communication channel for 18144 connected VNC clients. str is a non-empty string. If a 18145 VNC client sends rfbCutText having the prefix "str" 18146 then the part after it is processed as though it were 18147 sent via 'x11vnc -remote ...'. If it begins with 18148 neither 'cmd=' nor 'qry=' then 'qry=' is assumed. 18149 Any corresponding output text for that remote control 18150 command is sent back to all client as rfbCutText. 18151 The returned output is also prefixed with "str". 18152 Example: -remote_prefix DO_THIS: 18153 18154 Note that enabling -remote_prefix allows the remote 18155 VNC viewers to run x11vnc -remote commands. Do not 18156 use this option if they are not to be trusted. 18157 18158 -noremote Do not process any remote control commands or queries. 18159 -yesremote Do process remote control commands or queries. 18160 Default: -yesremote 18161 18162 A note about security wrt remote control commands. 18163 If someone can connect to the X display and change 18164 the property X11VNC_REMOTE, then they can remotely 18165 control x11vnc. Normally access to the X display is 18166 protected. Note that if they can modify X11VNC_REMOTE 18167 on the X server, they have enough permissions to also 18168 run their own x11vnc and thus have complete control 18169 of the desktop. If the "-connect /path/to/file" 18170 channel is being used, obviously anyone who can write 18171 to /path/to/file can remotely control x11vnc. So be 18172 sure to protect the X display and that file's write 18173 permissions. See -privremote below. 18174 18175 If you are paranoid and do not think -noremote is 18176 enough, to disable the X11VNC_REMOTE property channel 18177 completely use -novncconnect, or use the -safer option 18178 that shuts many things off. 18179 18180 -unsafe A few remote commands are disabled by default 18181 (currently: id:pick, accept:<cmd>, gone:<cmd>, and 18182 rawfb:setup:<cmd>) because they are associated with 18183 running external programs. If you specify -unsafe, then 18184 these remote-control commands are allowed. Note that 18185 you can still specify these parameters on the command 18186 line, they just cannot be invoked via remote-control. 18187 -safer Equivalent to: -novncconnect -noremote and prohibiting 18188 -gui and the -connect file. Shuts off communcation 18189 channels. 18190 -privremote Perform some sanity checks and disable remote-control 18191 commands if it appears that the X DISPLAY and/or 18192 connectfile can be accessed by other users. Once 18193 remote-control is disabled it cannot be turned back on. 18194 -nocmds No external commands (e.g. system(3), popen(3), exec(3)) 18195 will be run at all. 18196 -allowedcmds list "list" contains a comma separated list of the only 18197 external commands that can be run. The full list of 18198 associated options is: 18199 18200 stunnel, ssl, unixpw, WAIT, zeroconf, id, accept, 18201 afteraccept, gone, pipeinput, v4l-info, rawfb-setup, 18202 dt, gui, ssh, storepasswd, passwdfile, custom_passwd, 18203 findauth, crash. 18204 18205 See each option's help to learn the associated external 18206 command. Note that the -nocmds option takes precedence 18207 and disables all external commands. 18208 18209 -deny_all For use with -remote nodeny: start out denying all 18210 incoming clients until "-remote nodeny" is used to 18211 let them in. 18212 18213 18214 18215 These options are passed to LibVNCServer: 18216 18217 -rfbport port TCP port for RFB protocol 18218 -rfbwait time max time in ms to wait for RFB client 18219 -rfbauth passwd-file use authentication on RFB protocol 18220 (use 'storepasswd' to create a password file) 18221 -rfbversion 3.x Set the version of the RFB we choose to advertise 18222 -permitfiletransfer permit file transfer support 18223 -passwd plain-password use authentication 18224 (use plain-password as password, USE AT YOUR RISK) 18225 -deferupdate time time in ms to defer updates (default 40) 18226 -deferptrupdate time time in ms to defer pointer updates (default none) 18227 -desktop name VNC desktop name (default "LibVNCServer") 18228 -alwaysshared always treat new clients as shared 18229 -nevershared never treat new clients as shared 18230 -dontdisconnect don't disconnect existing clients when a new non-shared 18231 connection comes in (refuse new connection instead) 18232 -httpdir dir-path enable http server using dir-path home 18233 -httpport portnum use portnum for http connection 18234 -enablehttpproxy enable http proxy support 18235 -progressive height enable progressive updating for slow links 18236 -listen ipaddr listen for connections only on network interface with 18237 addr ipaddr. '-listen localhost' and hostname work too. 18238 18239 libvncserver-tight-extension options: 18240 -disablefiletransfer disable file transfer 18241 -ftproot string set ftp root 18242 18243 Pretty wild huh? Contact me if you have any questions or problems. 18244 18245 Personally, I use: 18246 x11vnc -rfbauth $HOME/.vnc/passwd -solid 18247
