| |
| Copyright (C) 2002-2010 Karl J. Runge <runge@karlrunge.com> |
| All rights reserved. |
| |
| x11vnc README file Date: Mon Dec 27 20:58:57 EST 2010 |
| |
| The following information is taken from these URLs: |
| |
| http://www.karlrunge.com/x11vnc/index.html |
| http://www.karlrunge.com/x11vnc/x11vnc_opts.html |
| ... |
| |
| they contain the most up to date info. |
| |
| |
| ======================================================================= |
| http://www.karlrunge.com/x11vnc/index.html: |
| |
| |
| _________________________________________________________________ |
| |
| x11vnc: a VNC server for real X displays |
| (to FAQ) (to Downloads) (to Building) (to Beta Test) |
| (to Donations) [PayPal] |
| |
| x11vnc allows one to view remotely and interact with real X displays |
| (i.e. a display corresponding to a physical monitor, keyboard, and |
| mouse) with any VNC viewer. In this way it plays the role for Unix/X11 |
| that WinVNC plays for Windows. |
| |
| It has built-in SSL/TLS encryption and 2048 bit RSA authentication, |
| including VeNCrypt support; UNIX account and password login support; |
| server-side scaling; single port HTTPS/HTTP+VNC; Zeroconf service |
| advertising; and TightVNC and UltraVNC file-transfer. It has also been |
| extended to work with non-X devices: natively on Mac OS X Aqua/Quartz, |
| webcams and TV tuner capture devices, and embedded Linux systems such |
| as Qtopia Core. Full IPv6 support is provided. More features are |
| described here. |
| |
| It also provides an encrypted Terminal Services mode (-create, -svc, |
| or -xdmsvc options) based on Unix usernames and Unix passwords where |
| the user does not need to memorize his VNC display/port number. |
| Normally a virtual X session (Xvfb) is created for each user, but it |
| also works with X sessions on physical hardware. See the tsvnc |
| terminal services mode of the SSVNC viewer for one way to take |
| advantage of this mode. |
| |
| I wrote x11vnc back in 2002 because x0rfbserver was basically |
| impossible to build on Solaris and had poor performance. The primary |
| x0rfbserver build problems centered around esoteric C++ toolkits. |
| x11vnc is written in plain C and needs only standard libraries and so |
| should work on nearly all Unixes, even very old ones. I also created |
| enhancements to improve the interactive response, added many features, |
| and etc. |
| |
| This page including the FAQ contains much information [*]; solutions |
| to many problems; and interesting applications, but nevertheless |
| please feel free to contact me if you have problems or questions (and |
| if I save you time or expense by giving you some of my time, please |
| consider a PayPal Donation.) Do check the FAQ and this page first; I |
| realize the pages are massive, but you can often use your browser's |
| find-in-page search action using a keyword to find the answer to your |
| problem or question. |
| |
| SSVNC: An x11vnc side-project provides an Enhanced TightVNC Viewer |
| package (SSVNC) for Unix, Windows, and Mac OS X with automatic SSL |
| and/or SSH tunnelling support, SSL Certificate creation, Saved |
| connection profiles, Zeroconf, VeNCrypt, and built-in Proxy support. |
| Added features for the TightVNC Unix viewer: NewFBSize, ZRLE encoding, |
| Viewer-side Scaling, cursor alphablending, low color modes, and |
| enhanced popup menu; UltraVNC extensions support for: File Transfer, |
| Text Chat, Single Window, Server Input, and 1/n Scaling extensions, |
| and UltraVNC DSM encryption. The SSVNC bundle could be placed on, say, |
| a USB memory stick for SSL/SSH VNC viewing from nearly any networked |
| computer. |
| |
| _________________________________________________________________ |
| |
| Announcements: |
| |
| Important: If you created any permanent SSL certificates (e.g. via |
| "x11vnc -ssl SAVE ...") on a Debian or Ubuntu system from Sept. 2006 |
| through May 2008, then those keys are likely extremely weak and can be |
| easily cracked. The certificate files should be deleted and recreated |
| on a non-Debian system or an updated one. See |
| http://www.debian.org/security/2008/dsa-1571 for details. The same |
| applies to SSH keys (not used by x11vnc directly, but many people use |
| SSH tunnels for VNC access.) |
| |
| FAQ moved: The huge FAQ has finally been moved to its own page. If you |
| are trying to follow someone's link to an FAQ once on this page it is |
| now a broken link. Try inserting the string "faq.html", e.g.: |
| from: http://www.karlrunge.com/x11vnc/#faq-singleclick |
| to: http://www.karlrunge.com/x11vnc/faq.html#faq-singleclick |
| |
| Apologies for the inconvenience, unfortunately it is not possible to |
| automatically redirect to the new page since the '#' anchor is not |
| sent to the webserver. |
| |
| _________________________________________________________________ |
| |
| Background: |
| |
| VNC (Virtual Network Computing) is a very useful network graphics |
| protocol (applications running on one computer but displaying their |
| windows on another) in the spirit of X, however, unlike X, the |
| viewing-end is very simple and maintains no state. It is a remote |
| framebuffer (RFB) protocol. |
| |
| Some VNC links: |
| * http://www.realvnc.com |
| * http://www.tightvnc.com |
| * http://www.ultravnc.com/ |
| * http://www.testplant.com/products/vine_server/OS_X |
| |
| For Unix, the traditional VNC implementation includes a "virtual" X11 |
| server Xvnc (usually launched via the vncserver command) that is not |
| associated with a physical display, but provides a "fake" one X11 |
| clients (xterm, firefox, etc.) can attach to. A remote user then |
| connects to Xvnc via the VNC client vncviewer from anywhere on the |
| network to view and interact with the whole virtual X11 desktop. |
| |
| The VNC protocol is in most cases better suited for remote connections |
| with low bandwidth and high latency than is the X11 protocol because |
| it involves far fewer "roundtrips" (an exception is the cached pixmap |
| data on the viewing-end provided by X.) Also, with no state maintained |
| the viewing-end can crash, be rebooted, or relocated and the |
| applications and desktop continue running. Not so with X11. |
| |
| So the standard Xvnc/vncserver program is very useful, I use it for |
| things like: |
| * Desktop conferencing with other users (e.g. code reviews.) |
| * Long running apps/tasks I want to be able to view from many places |
| (e.g. from home and work.) |
| * Motif, GNOME, and similar applications that would yield very poor |
| performance over a high latency link. |
| |
| However, sometimes one wants to connect to a real X11 display (i.e. |
| one attached to a physical monitor, keyboard, and mouse: a Workstation |
| or a SunRay session) from far away. Maybe you want to close down an |
| application cleanly rather than using kill, or want to work a bit in |
| an already running application, or would like to help a distant |
| colleague solve a problem with their desktop, or would just like to |
| work out on the deck for a while. This is where x11vnc is useful. |
| _________________________________________________________________ |
| |
| How to use x11vnc: |
| |
| In this basic example let's assume the remote machine with the X |
| display you wish to view is "far-away.east:0" and the workstation you |
| are presently working at is "sitting-here.west". |
| |
| Step 0. Download x11vnc (see below) and have it available to run on |
| far-away.east (on some linux distros it is as easy as "apt-get install |
| x11vnc", "emerge x11vnc", etc.) Similarly, have a VNC viewer (e.g. |
| vncviewer) ready to run on sitting-here.west. We recommend TightVNC |
| Viewers (see also our SSVNC viewer.) |
| |
| Step 1. By some means log in to far-away.east and get a command shell |
| running there. You can use ssh, or even rlogin, telnet, or any other |
| method to do this. We do this because the x11vnc process needs to be |
| run on the same machine the X server process is running on (otherwise |
| things would be extremely slow.) |
| |
| Step 2. In that far-away.east shell (with command prompt "far-away>" |
| in this example) run x11vnc directed at the far-away.east X session |
| display: |
| |
| far-away> x11vnc -display :0 |
| |
| You could have also set the environment variable DISPLAY=:0 instead of |
| using "-display :0". This step attaches x11vnc to the far-away.east:0 |
| X display (i.e. no viewer clients yet.) |
| |
| Common Gotcha: To get X11 permissions right, you may also need to set |
| the XAUTHORITY environment variable (or use the -auth option) to point |
| to the correct MIT-MAGIC-COOKIE file (e.g. /home/joe/.Xauthority.) If |
| x11vnc does not have the authority to connect to the display it exits |
| immediately. More on how to fix this below. |
| |
| If you suspect an X11 permissions problem do this simple test: while |
| sitting at the physical X display open a terminal window |
| (gnome-terminal, xterm, etc.) You should be able to run x11vnc |
| successfully in that terminal without any need for command line |
| options. If that works OK then you know X11 permissions are the only |
| thing preventing it from working when you try to start x11vnc via a |
| remote shell. Then fix this with the tips below. |
| |
| Note as of Feb/2007 you can also try the -find option instead of |
| "-display ..." and see if that finds your display and Xauthority. Note |
| as of Dec/2009 the -findauth and "-auth guess" options may be helpful |
| as well. |
| (End of Common Gotcha) |
| |
| When x11vnc starts up there will then be much chatter printed out (use |
| "-q" to quiet it), until it finally says something like: |
| . |
| . |
| 13/05/2004 14:59:54 Autoprobing selected port 5900 |
| 13/05/2004 14:59:54 screen setup finished. |
| 13/05/2004 14:59:54 |
| 13/05/2004 14:59:54 The VNC desktop is far-away:0 |
| PORT=5900 |
| |
| which means all is OK, and we are ready for the final step. |
| |
| Step 3. At the place where you are sitting (sitting-here.west in this |
| example) you now want to run a VNC viewer program. There are VNC |
| viewers for Unix, Windows, MacOS, Java-enabled web browsers, and even |
| for PDA's like the Palm Pilot and Cell Phones! You can use any of them |
| to connect to x11vnc (see the above VNC links under "Background:" on |
| how to obtain a viewer for your platform or see this FAQ. For Solaris, |
| vncviewer is available in the Companion CD package SFWvnc.) |
| |
| In this example we'll use the Unix vncviewer program on sitting-here |
| by typing the following command in a second terminal window: |
| |
| sitting-here> vncviewer far-away.east:0 |
| |
| That should pop up a viewer window on sitting-here.west showing and |
| allowing interaction with the far-away.east:0 X11 desktop. Pretty |
| nifty! When finished, exit the viewer: the remote x11vnc process will |
| shutdown automatically (or you can use the -forever option to have it |
| wait for additional viewer connections.) |
| |
| Common Gotcha: Nowadays there will likely be a host-level firewall on |
| the x11vnc side that is blocking remote access to the VNC port (e.g. |
| 5900.) You will either have to open up that port (or a range of ports) |
| in your firewall administration tool, or try the SSH tunnelling method |
| below (even still the firewall must allow in the SSH port, 22.) |
| |
| |
| Shortcut: Of course if you left x11vnc running on far-away.east:0 in a |
| terminal window with the -forever option or as a service, you'd only |
| have to do Step 3 as you moved around. Be sure to use a VNC Password |
| or other measures if you do that. |
| |
| |
| Super Shortcut: Here is a potentially very easy way to get all of it |
| working. |
| * Have x11vnc (0.9.3 or later) available to run on the remote host |
| (i.e. in $PATH.) |
| * Download and unpack a SSVNC bundle (1.0.19 or later, e.g. |
| ssvnc_no_windows-1.0.28.tar.gz) on the Viewer-side machine. |
| * Start the SSVNC Terminal Services mode GUI: ./ssvnc/bin/tsvnc |
| * Enter your remote username@hostname (e.g. fred@far-away.east) in |
| the "VNC Terminal Server" entry. |
| * Click "Connect". |
| |
| That will do an SSH to username@hostname and start up x11vnc and then |
| connect a VNC Viewer through the SSH encrypted tunnel. |
| |
| There are a number of things assumed here, first that you are able to |
| SSH into the remote host; i.e. that you have a Unix account there and |
| the SSH server is running. On Unix and MacOS X it is assumed that the |
| ssh client command is available on the local machine (on Windows a |
| plink binary is included in the SSVNC bundle.) Finally, it is assumed |
| that you are already logged into an X session on the remote machine, |
| e.g. your workstation (otherwise, a virtual X server, e.g. Xvfb, will |
| be started for you.) |
| |
| In some cases the remote SSH server will not run commands with the |
| same $PATH that you normally have in your shell there. In this case |
| click on Options -> Advanced -> X11VNC Options, and type in the |
| location of the x11vnc binary under "Full Path". (End of Super |
| Shortcut) |
| |
| |
| Desktop Sharing: The above more or less assumed nobody was sitting at |
| the workstation display "far-away.east:0". This is often the case: a |
| user wants to access her workstation remotely. Another usage pattern |
| has the user sitting at "far-away.east:0" and invites one or more |
| other people to view and interact with his desktop. Perhaps the user |
| gives a demo or presentation this way (using the telephone for vocal |
| communication.) A "Remote Help Desk" mode would be similar: a |
| technician connects remotely to the user's desktop to interactively |
| solve a problem the user is having. |
| |
| For these cases it should be obvious how it is done. The above steps |
| will work, but more easily the user sitting at far-away.east:0 simply |
| starts up x11vnc from a terminal window, after which the guests would |
| start their VNC viewers. For this usage mode the "-connect |
| host1,host2" option may be of use to automatically connect to the |
| vncviewers in "-listen" mode on the list of hosts. |
| _________________________________________________________________ |
| |
| Tunnelling x11vnc via SSH: |
| |
| The above example had no security or privacy at all. When logging into |
| remote machines (certainly when going over the internet) it is best to |
| use ssh, or use a VPN (for a VPN, Virtual Private Network, the above |
| example should be pretty safe.) |
| |
| For x11vnc one can tunnel the VNC protocol through an encrypted ssh |
| channel. It would look something like running the following commands: |
| sitting-here> ssh -t -L 5900:localhost:5900 far-away.east 'x11vnc -localhost |
| -display :0' |
| |
| (you will likely have to provide passwords/passphrases to login from |
| sitting-here into your far-away.east Unix account; we assume you have |
| a login account on far-away.east and it is running the SSH server) |
| |
| And then in another terminal window on sitting-here run the command: |
| sitting-here> vncviewer -encodings "copyrect tight zrle hextile" localhost:0 |
| |
| Note: The -encodings option is very important: vncviewer will often |
| default to "raw" encoding if it thinks the connection is to the local |
| machine, and so vncviewer gets tricked this way by the ssh |
| redirection. "raw" encoding will be extremely slow over a networked |
| link, so you need to force the issue with -encodings "copyrect tight |
| ...". Nowadays, not all viewers use the -encodings option, try |
| "-PreferredEncoding=ZRLE" (although the newer viewers seem to |
| autodetect well when to use raw or not.) |
| |
| Note that "x11vnc -localhost ..." limits incoming vncviewer |
| connections to only those from the same machine. This is very natural |
| for ssh tunnelling (the redirection appears to come from the same |
| machine.) Use of a VNC password is also strongly recommended. |
| |
| Note also the -t we used above (force allocate pseudoterminal), it |
| actually seems to improve interactive typing response via VNC! |
| |
| You may want to add the -C option to ssh to enable compression. The |
| VNC compression is not perfect, and so this may help a bit. However, |
| over a fast LAN you probably don't want to enable SSH compression |
| because it can slow things down. Try both and see which is faster. |
| |
| If your username is different on the remote machine use something |
| like: "fred@far-away.east" in the above ssh command line. |
| |
| Some VNC viewers will do the ssh tunnelling for you automatically, the |
| TightVNC Unix vncviewer does this when the "-via far-away.east" option |
| is supplied to it (this requires x11vnc to be already running on |
| far-away.east or having it started by inetd(8).) See the 3rd script |
| example below for more info. |
| |
| SSVNC: You may also want to look at the Enhanced TightVNC Viewer |
| (ssvnc) bundles because they contain scripts and GUIs to automatically |
| set up SSH tunnels (e.g. the GUI, "ssvnc", does it automatically and |
| so does this command: "ssvnc_cmd -ssh user@far-away.east:0") and can |
| even start up x11vnc as well. |
| |
| The Terminal Services mode of SSVNC is perhaps the easiest way to use |
| x11vnc. You just need to have x11vnc available in $PATH on the remote |
| side (and can SSH to the host), and then on the viewer-side you type |
| something like: |
| tsvnc fred@far-away.east |
| |
| everything else is done automatically for you. Normally this will |
| start a virtual Terminal Services X session (RAM-only), but if you |
| already have a real X session up on the physical hardware it will find |
| that one for you. |
| |
| Gateways: If the machine you SSH into is not the same machine with |
| the X display you wish to view (e.g. your company provides incoming |
| SSH access to a gateway machine), then you need to change the above |
| to, e.g.: "-L 5900:OtherHost:5900": |
| sitting-here> ssh -t -L 5900:OtherHost:5900 gateway.east |
| |
| Where gateway.east is the internet hostname (or IP) of the gateway |
| machine (SSH server.) 'OtherHost' might be, e.g., freds-pc or |
| 192.168.2.33 (it is OK for these to be private hostnames or private IP |
| addresses, the host in -L is relative to the remote server side.) |
| |
| Once logged in, you'll need to do a second login (ssh, rsh, etc.) to |
| the workstation machine 'OtherHost' and then start up x11vnc on it (if |
| it isn't already running.) (The "-connect gateway:59xx" option may be |
| another alternative here with the viewer already in -listen mode.) For |
| an automatic way to use a gateway and have all the network traffic |
| encrypted (including inside the firewall) see Chaining SSH's. |
| |
| These gateway access modes also can be done automatically for you via |
| the "Proxy/Gateway" setting in SSVNC (including the Chaining SSH's |
| case, "Double Proxy".) |
| |
| Firewalls/Routers: |
| |
| A lot of people have inexpensive devices for home or office that act |
| as a Firewall and Router to the machines inside on a private LAN. One |
| can usually configure the Firewall/Router from inside the LAN via a |
| web browser. |
| |
| Often having a Firewall/Router sitting between the vncviewer and |
| x11vnc will make it impossible for the viewer to connect to x11vnc. |
| |
| One thing that can be done is to redirect a port on the |
| Firewall/Router to, say, the SSH port (22) on an inside machine (how |
| to do this depends on your particular Firewall/Router, often the |
| router config URL is http://192.168.100.1 See www.portforward.com for |
| more info.) This way you reach these computers from anywhere on the |
| Internet and use x11vnc to view X sessions running on them. |
| |
| Suppose you configured the Firewall/Router to redirect these ports to |
| two internal machines: |
| Port 12300 -> 192.168.1.3, Port 22 (SSH) |
| Port 12301 -> 192.168.1.4, Port 22 (SSH) |
| |
| (where 192.168.1.3 is "jills-pc" and 192.168.1.4 is "freds-pc".) Then |
| the ssh's would look something like: |
| sitting-here> ssh -t -p 12300 -L 5900:localhost:5900 jill@far-away.east 'x11v |
| nc -localhost -display :0' |
| sitting-here> ssh -t -p 12301 -L 5900:localhost:5900 fred@far-away.east 'x11v |
| nc -localhost -display :0' |
| |
| Where far-away.east means the hostname (or IP) that the |
| Router/Firewall is using (for home setups this is usually the IP |
| gotten from your ISP via DHCP, the site http://www.whatismyip.com/ is |
| a convenient way to determine what it is.) |
| |
| It is a good idea to add some obscurity to accessing your system via |
| SSH by using some high random port (e.g. 12300 in the above example.) |
| If you can't remember it, or are otherwise not worried about port |
| scanners detecting the presence of your SSH server and there is just |
| one internal PC involved you could map 22: |
| Port 22 -> 192.168.1.3, Port 22 (SSH) |
| |
| Again, this SSH gateway access can be done automatically for you via |
| the "Proxy/Gateway" setting in SSVNC. And under the "Remote SSH |
| Command" setting you can enter the x11vnc -localhost -display :0. |
| |
| Host-Level-Firewalls: even with the hardware Firewall/Router problem |
| solved via a port redirection, most PC systems have their own Host |
| level "firewalls" enabled to protect users from themselves. I.e. the |
| system itself blocks all incoming connections. So you will need to see |
| what is needed to configure it to allow in the port (e.g. 22) that you |
| desire. E.g. Yast, Firestarter, iptables(1), etc.. |
| |
| VNC Ports and Firewalls: The above discussion was for configuring the |
| Firewall/Router to let in port 22 (SSH), but the same thing can be |
| done for the default VNC port 5900: |
| Port 5900 -> 192.168.1.3, Port 5900 (VNC) |
| Port 5901 -> 192.168.1.4, Port 5900 (VNC) |
| |
| (where 192.168.1.3 is "jills-pc" and 192.168.1.4 is "freds-pc".) This |
| could be used for normal, unencrypted connections and also for SSL |
| encrypted ones. |
| |
| The VNC displays to enter in the VNC viewer would be, say, |
| "far-away.east:0" to reach jills-pc and "far-away.east:1" to reach |
| freds-pc. We assume above that x11vnc is using port 5900 (and any |
| Host-Level-firewalls on jills-pc has been configured to let that port |
| in.) Use the "-rfbport" option to tell which port x11vnc should listen |
| on. |
| |
| For a home system one likely does not have a hostname and would have |
| to use the IP address, say, "24.56.78.93:0". E.g.: |
| vncviewer 24.56.78.93:0 |
| |
| You may want to choose a more obscure port on the router side, e.g. |
| 5944, to avoid a lot of port scans finding your VNC server. For 5944 |
| you would tell the viewer to use: |
| vncviewer 24.56.78.93:44 |
| |
| The IP address would need to be communicated to the person running the |
| VNC Viewer. The site http://www.whatismyip.com/ can help here. |
| |
| _________________________________________________________________ |
| |
| Scripts to automate ssh tunneling: As discussed below, there may be |
| some problems with port 5900 being available. If that happens, the |
| above port and display numbers may change a bit (e.g. -> 5901 and :1). |
| However, if you "know" port 5900 will be free on the local and remote |
| machines, you can easily automate the above two steps by using the |
| x11vnc option -bg (forks into background after connection to the |
| display is set up) or using the -f option of ssh. Some example scripts |
| are shown below. Feel free to try the ssh -C to enable its compression |
| and see if that speeds things up noticeably. |
| _________________________________________________________________ |
| |
| #1. A simple example script, assuming no problems with port 5900 being |
| taken on the local or remote sides, looks like: |
| #!/bin/sh |
| # usage: x11vnc_ssh <host>:<xdisplay> |
| # e.g.: x11vnc_ssh snoopy.peanuts.com:0 |
| # (user@host:N also works) |
| |
| host=`echo $1 | awk -F: '{print $1}'` |
| disp=`echo $1 | awk -F: '{print $2}'` |
| if [ "x$disp" = "x" ]; then disp=0; fi |
| |
| cmd="x11vnc -display :$disp -localhost -rfbauth .vnc/passwd" |
| enc="copyrect tight zrle hextile zlib corre rre raw" |
| |
| ssh -f -t -L 5900:localhost:5900 $host "$cmd" |
| |
| for i in 1 2 3 |
| do |
| sleep 2 |
| if vncviewer -encodings "$enc" :0; then break; fi |
| done |
| |
| See also rx11vnc.pl below. |
| _________________________________________________________________ |
| |
| #2. Another method is to start the VNC viewer in listen mode |
| "vncviewer -listen" and have x11vnc initiate a reverse connection |
| using the -connect option: |
| #!/bin/sh |
| # usage: x11vnc_ssh <host>:<xdisplay> |
| # e.g.: x11vnc_ssh snoopy.peanuts.com:0 |
| # (user@host:N also works) |
| |
| host=`echo $1 | awk -F: '{print $1}'` |
| disp=`echo $1 | awk -F: '{print $2}'` |
| if [ "x$disp" = "x" ]; then disp=0; fi |
| |
| cmd="x11vnc -display :$disp -localhost -connect localhost" # <== note new opt |
| ion |
| enc="copyrect tight zrle hextile zlib corre rre raw" |
| |
| vncviewer -encodings "$enc" -listen & |
| pid=$! |
| ssh -t -R 5500:localhost:5500 $host "$cmd" |
| kill $pid |
| |
| Note the use of the ssh option "-R" instead of "-L" to set up a remote |
| port redirection. |
| _________________________________________________________________ |
| |
| #3. A third way is specific to the TightVNC vncviewer special option |
| -via for gateways. The only tricky part is we need to start up x11vnc |
| and give it some time (5 seconds in this example) to start listening |
| for connections (so we cannot use the TightVNC default setting for |
| VNC_VIA_CMD): |
| #!/bin/sh |
| # usage: x11vnc_ssh <host>:<xdisplay> |
| # e.g.: x11vnc_ssh snoopy.peanuts.com:0 |
| |
| host=`echo $1 | awk -F: '{print $1}'` |
| disp=`echo $1 | awk -F: '{print $2}'` |
| if [ "x$disp" = "x" ]; then disp=0; fi |
| |
| VNC_VIA_CMD="ssh -f -t -L %L:%H:%R %G x11vnc -localhost -rfbport 5900 -display |
| :$disp; sleep 5" |
| export VNC_VIA_CMD |
| |
| vncviewer -via $host localhost:0 # must be TightVNC vncviewer. |
| |
| Of course if you already have the x11vnc running waiting for |
| connections (or have it started out of inetd(8)), you can simply use |
| the TightVNC "vncviewer -via gateway host:port" in its default mode to |
| provide secure ssh tunnelling. |
| _________________________________________________________________ |
| |
| |
| |
| VNC password file: Also note in the #1. example script that the option |
| "-rfbauth .vnc/passwd" provides additional protection by requiring a |
| VNC password for every VNC viewer that connects. The vncpasswd or |
| storepasswd programs, or the x11vnc -storepasswd option can be used to |
| create the password file. x11vnc also has the slightly less secure |
| -passwdfile and "-passwd XXXXX" options to specify passwords. |
| |
| Very Important: It is up to YOU to tell x11vnc to use password |
| protection (-rfbauth or -passwdfile), it will NOT do it for you |
| automatically or force you to (use -usepw if you want to be forced |
| to.) The same goes for encrypting the channel between the viewer and |
| x11vnc: it is up to you to use ssh, stunnel, -ssl mode, a VPN, etc. |
| (use the Enhanced TightVNC Viewer (SSVNC) GUI if you want to be forced |
| to use SSL or SSH.) For additional safety, also look into the -allow |
| and -localhost options and building x11vnc with tcp_wrappers support |
| to limit host access. |
| |
| _________________________________________________________________ |
| |
| Tunnelling x11vnc via SSL/TLS: |
| |
| One can also encrypt the VNC traffic using an SSL/TLS tunnel such as |
| stunnel.mirt.net (also stunnel.org) or using the built-in (Mar/2006) |
| -ssl openssl mode. A SSL-enabled Java applet VNC Viewer is also |
| provided in the x11vnc package (and https can be used to download it.) |
| |
| Although not as ubiquitous as ssh, SSL tunnelling still provides a |
| useful alternative. See this FAQ on -ssl and -stunnel modes for |
| details and examples. |
| |
| The Enhanced TightVNC Viewer (SSVNC) bundles contain some convenient |
| utilities to automatically set up an SSL tunnel from the viewer-side |
| (i.e. to connect to "x11vnc -ssl ...".) And many other enhancements |
| too. |
| _________________________________________________________________ |
| |
| Downloading x11vnc: |
| |
| x11vnc is a contributed program to the LibVNCServer project at |
| SourceForge.net. I use libvncserver for all of the VNC aspects; I |
| couldn't have done without it. The full source code may be found and |
| downloaded (either file-release tarball or GIT tree) from the above |
| link. As of Sep 2010, the x11vnc-0.9.12.tar.gz source package is |
| released (recommended download). The x11vnc 0.9.12 release notes. |
| |
| The x11vnc package is the subset of the libvncserver package needed to |
| build the x11vnc program. Also, you can get a copy of my latest, |
| bleeding edge x11vnc-0.9.13-dev.tar.gz tarball to build the most up to |
| date one. |
| |
| Precompiled Binaries/Packages: See the FAQ below for information |
| about where you might obtain a precompiled x11vnc binary from 3rd |
| parties and some ones I create. |
| |
| VNC Viewers: To obtain VNC viewers for the viewing side (Windows, Mac |
| OS, or Unix) try these links: |
| * http://www.tightvnc.com/download.html |
| * http://www.realvnc.com/download-free.html |
| * http://sourceforge.net/projects/cotvnc/ |
| * http://www.ultravnc.com/ |
| * Our Enhanced TightVNC Viewer (SSVNC) |
| |
| [ssvnc.gif] |
| |
| |
| More tools: Here is a ssh/rsh wrapper script rx11vnc that attempts to |
| automatically do the above Steps 1-3 for you (provided you have |
| ssh/rsh login permission on the machine x11vnc is to be run on.) The |
| above example would be: "rx11vnc far-away.east:0" typed into a shell |
| on sitting-here.west. Also included is an experimental script |
| rx11vnc.pl that attempts to tunnel the vnc traffic through an ssh port |
| redirection (and does not assume port 5900 is free.) Have a look at |
| them to see what they do and customize as needed: |
| * rx11vnc wrapper script |
| * rx11vnc.pl wrapper script to tunnel traffic thru ssh |
| |
| _________________________________________________________________ |
| |
| Building x11vnc: |
| |
| Make sure you have all the needed build/compile/development packages |
| installed (e.g. Linux distributions foolishly don't install them by |
| default.) See this build FAQ for more details. |
| |
| If your OS has libjpeg.so and libz.so in standard locations you can |
| build as follows (example given for the 0.9.12 release of x11vnc: |
| replace with the version you downloaded): |
| (un-tar the x11vnc+libvncserver tarball) |
| # gzip -dc x11vnc-0.9.12.tar.gz | tar -xvf - |
| |
| (cd to the source directory) |
| # cd x11vnc-0.9.12 |
| |
| (run configure and then run make) |
| # ./configure |
| # make |
| |
| (if all went OK, copy x11vnc to the desired destination, e.g. $HOME/bin) |
| # cp ./x11vnc/x11vnc $HOME/bin |
| |
| Or do make install, it will probably install to /usr/local/bin (run |
| ./configure --help for information on customizing your configuration, |
| e.g. --prefix=/my/place.) You can now run it via typing "x11vnc", |
| "x11vnc -help | more", "x11vnc -forever -shared -display :0", etc. |
| |
| |
| Note: Currently gcc is recommended to build libvncserver. In some |
| cases it will build with non-gcc compilers, but the resulting binary |
| sometimes fails to run properly. For Solaris pre-built gcc binaries |
| are at http://www.sunfreeware.com/. Some Solaris pre-built x11vnc |
| binaries are here. |
| |
| However, one user reports it does work fine when built with Sun Studio |
| 10, so YMMV. In fact, here is a little build script to do this on |
| Solaris 10: |
| #!/bin/sh |
| PATH=/usr/ccs/bin:/opt/SUNWspro/bin:$PATH; export PATH |
| |
| CC='cc' \ |
| CFLAGS='-xO4' \ |
| LDFLAGS='-L/usr/sfw/lib -L/usr/X11/lib -R/usr/sfw/lib -R/usr/X11/lib' \ |
| CPPFLAGS='-I /usr/sfw/include -I/usr/X11/include' \ |
| ./configure |
| |
| MAKE="make -e" |
| AM_CFLAGS="" |
| export MAKE AM_CFLAGS |
| $MAKE |
| |
| In general you can use the "make -e" trick if you don't like |
| libvncserver's choice of AM_CFLAGS. See the build scripts below for |
| more ideas. Scripts similar to the above have been shown to work with |
| vendor C compilers on HP-UX (ccom: HP92453-01) and Tru64 (Compaq C |
| V6.5-011.) |
| |
| You can find information on Misc. Build problems here. |
| |
| _________________________________________________________________ |
| |
| Building on Solaris, FreeBSD, etc: Depending on your version of |
| Solaris or other Unix OS the jpeg and/or zlib libraries may be in |
| non-standard places (e.g. /usr/local, /usr/sfw, /opt/sfw, etc.) |
| |
| Note: If configure cannot find these two libraries then TightVNC and |
| ZRLE encoding support will be disabled, and you don't want that!!! The |
| TightVNC encoding gives very good compression and performance, it even |
| makes a noticeable difference over a fast LAN. |
| |
| |
| Shortcuts: On Solaris 10 you can pick up almost everything just by |
| insuring that your PATH has /usr/sfw/bin (for gcc) and /usr/ccs/bin |
| (for other build tools), e.g.: |
| env PATH=/usr/sfw/bin:/usr/ccs/bin:$PATH sh -c './configure; make' |
| |
| (The only thing this misses is /usr/X11/lib/libXrandr.so.2, which is |
| for the little used -xrandr option, see the script below to pick it up |
| as well.) |
| |
| |
| libjpeg is included in Solaris 9 and later (/usr/sfw/include and |
| /usr/sfw/lib), and zlib in Solaris 8 and later (/usr/include and |
| /usr/lib.) So on Solaris 9 you can pick up everything with something |
| like this: |
| env PATH=/usr/local/bin:/usr/ccs/bin:$PATH sh -c './configure --with-jpeg=/us |
| r/sfw; make' |
| |
| assuming your gcc is in /usr/local/bin and x11vnc 0.7.1 or later. |
| These are getting pretty long, see those assignments split up in the |
| build script below. |
| |
| |
| If your system does not have these libraries at all you can get the |
| source for the libraries to build them: libjpeg is available at |
| ftp://ftp.uu.net/graphics/jpeg/ and zlib at http://www.gzip.org/zlib/. |
| See also http://www.sunfreeware.com/ for Solaris binary packages of |
| these libraries as well as for gcc. Normally they will install into |
| /usr/local but you can install them anywhere with the |
| --prefix=/path/to/anywhere, etc. |
| |
| |
| Here is a build script that indicates one way to pass the library |
| locations information to the libvncserver configuration via the |
| CPPFLAGS and LDFLAGS environment variables. |
| ---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8 |
| <--- |
| #!/bin/sh |
| |
| # Build script for Solaris, etc, with gcc, libjpeg and libz in |
| # non-standard locations. |
| |
| # set to get your gcc, etc: |
| # |
| PATH=/path/to/gcc/bin:/usr/ccs/bin:/usr/sfw/bin:$PATH |
| |
| JPEG=/path/to/jpeg # set to maybe "/usr/local", "/usr/sfw", or "/opt/sfw" |
| ZLIB=/path/to/zlib # set to maybe "/usr/local", "/usr/sfw", or "/opt/sfw" |
| |
| # Below we assume headers in $JPEG/include and $ZLIB/include and the |
| # shared libraries are in $JPEG/lib and $ZLIB/lib. If your situation |
| # is different change the locations in the two lines below. |
| # |
| CPPFLAGS="-I $JPEG/include -I $ZLIB/include" |
| LDFLAGS="-L$JPEG/lib -R $JPEG/lib -L$ZLIB/lib -R $ZLIB/lib" |
| |
| # These two lines may not be needed on more recent Solaris releases: |
| # |
| CPPFLAGS="$CPPFLAGS -I /usr/openwin/include" |
| LDFLAGS="$LDFLAGS -L/usr/openwin/lib -R /usr/openwin/lib" |
| |
| # These are for libXrandr.so on Solaris 10: |
| # |
| CPPFLAGS="$CPPFLAGS -I /usr/X11/include" |
| LDFLAGS="$LDFLAGS -L/usr/X11/lib -R /usr/X11/lib" |
| |
| # Everything needs to built with _REENTRANT for thread safe errno: |
| # |
| CPPFLAGS="$CPPFLAGS -D_REENTRANT" |
| |
| export PATH CPPFLAGS LDFLAGS |
| |
| ./configure |
| make |
| |
| ls -l ./x11vnc/x11vnc |
| |
| ---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8 |
| <--- |
| |
| Then do make install or copy the x11vnc binary to your desired |
| destination. |
| |
| BTW, To run a shell script, just cut-and-paste the above into a file, |
| say "myscript", then modify the "/path/to/..." items to correspond to |
| your system/environment, and then type: "sh myscript" to run it. |
| |
| Note that on Solaris make is /usr/ccs/bin/make, so that is why the |
| above puts /usr/ccs/bin in PATH. Other important build utilities are |
| there too: ld, ar, etc. Also, it is probably a bad idea to have |
| /usr/ucb in your PATH while building. |
| |
| Starting with the 0.7.1 x11vnc release the "configure --with-jpeg=DIR |
| --with-zlib=DIR" options are handy if you want to avoid making a |
| script. |
| |
| If you need to link OpenSSL libssl.a on Solaris see this method. |
| |
| If you need to build on Solaris 2.5.1 or earlier or other older Unix |
| OS's, see this workaround FAQ. |
| |
| |
| Building on FreeBSD, OpenBSD, ...: The jpeg libraries seem to be in |
| /usr/local or /usr/pkg on these OS's. You won't need the openwin stuff |
| in the above script (but you may need /usr/X11R6/....) Also starting |
| with the 0.7.1 x11vnc release, this usually works: |
| ./configure --with-jpeg=/usr/local |
| make |
| |
| |
| Building on HP-UX: For jpeg and zlib you will need to do the same |
| sort of thing as described above for Solaris. You set CPPFLAGS and |
| LDFLAGS to find them (see below for an example.) You do not need to do |
| any of the above /usr/openwin stuff. Also, HP-UX does not seem to |
| support -R, so get rid of the -R items in LDFLAGS. Because of this, at |
| runtime you may need to set LD_LIBRARY_PATH or SHLIB_PATH to indicate |
| the directory paths so the libraries can be found. It is a good idea |
| to have static archives, e.g. libz.a and libjpeg.a for the nonstandard |
| libraries so that they get bolted into the x11vnc binary (and so won't |
| get "lost".) |
| |
| Here is what we recently did to build x11vnc 0.7.2 on HP-UX 11.11 |
| ./configure --with-jpeg=$HOME/hpux/jpeg --with-zlib=$HOME/hpux/zlib |
| make |
| |
| Where we had static archives (libjpeg.a, libz.a) only and header files |
| in the $HOME/hpux/... directories as discussed for the build script. |
| |
| On HP-UX 11.23 and 11.31 we have had problems compiling with gcc. |
| "/usr/include/rpc/auth.h:87: error: field 'syncaddr' has incomplete |
| type". As a workaround for x11vnc 0.9.4 and later set your CPPFLAGS to |
| include: |
| CPPFLAGS="-DIGNORE_GETSPNAM" |
| export CPPFLAGS |
| |
| This disables a very rare usage mode for -unixpw_nis by not trying |
| getspnam(3). |
| |
| Using HP-UX's C compiler on 11.23 and 11.31 we have some severe |
| compiler errors that have not been worked around yet. If you need to |
| do this, contact me and I will give you a drastic recipe that will |
| produce a working binary. |
| |
| |
| Building on AIX: AIX: one user had to add the "X11.adt" package to |
| AIX 4.3.3 and 5.2 to get build header files like XShm.h, etc. You may |
| also want to make sure that /usr/lpp/X11/include, etc is being picked |
| up by the configure and make. |
| |
| For a recent build on AIX 5.3 we needed to add these CFLAGS to be able |
| to build with gcc: |
| env CFLAGS='-maix64 -Xlinker -bbigtoc' ./configure ... |
| |
| we also built our own libjpeg and libz using -maix64. |
| |
| BTW, one way to run an Xvfb-like virtual X server for testing on AIX |
| is something like "/usr/bin/X11/X -force -vfb -ac :1". |
| |
| |
| Building on Mac OS X: There is now native Mac OS X support for |
| x11vnc by using the raw framebuffer feature. This mode does not use or |
| need X11 at all. To build you may need to disable X11: |
| ./configure --without-x ... |
| make |
| |
| However, if your system has the Mac OS X build package for X11 apps |
| you will not need to supply the "--without-x" option (in this case the |
| resulting x11vnc would be able to export both the native Mac OS X |
| display and windows displayed in the XDarwin X server.) Be sure to |
| include the ./configure option to find libjpeg on your system. |
| |
| |
| OpenSSL: Starting with version 0.8.3 x11vnc can now be built with |
| SSL/TLS support. For this to be enabled the libssl.so library needs to |
| be available at build time. So you may need to have additional |
| CPPFLAGS and LDFLAGS items if your libssl.so is in a non-standard |
| place. As of x11vnc 0.9.4 there is also the --with-ssl=DIR configure |
| option. |
| |
| On Solaris using static archives libssl.a and libcrypto.a instead of |
| .so shared libraries (e.g. from www.sunfreeware.com), we found we |
| needed to also set LDFLAGS as follows to get the configure to work: |
| env LDFLAGS='-lsocket -ldl' ./configure --with-ssl=/path/to/openssl ... |
| make |
| |
| _________________________________________________________________ |
| |
| Beta Testing: |
| |
| I don't have any formal beta-testers for the releases of x11vnc, so |
| I'd appreciate any additional testing very much. |
| |
| Thanks to those who suggested features and helped beta test x11vnc |
| 0.9.12 released in Sep 2010! |
| |
| Please help test and debug the 0.9.13 version for release sometime in |
| Winter 2010. |
| |
| The version 0.9.13 beta tarball is kept here: |
| x11vnc-0.9.13-dev.tar.gz |
| |
| There are also some Linux, Solaris, Mac OS X, and other OS test |
| binaries here. Please kick the tires and report bugs, performance |
| regressions, undesired behavior, etc. to me. |
| |
| To aid testing of the built-in SSL/TLS support for x11vnc, a number of |
| VNC Viewer packages for Unix, Mac OS X, and Windows have been created |
| that provide SSL Support for the TightVNC Viewer (this is done by |
| wrapper scripts and a GUI that starts STUNNEL.) It should be pretty |
| convenient for automatic SSL and SSH connections. It is described in |
| detail at and can be downloaded from the Enhanced TightVNC Viewer |
| (SSVNC) page. The SSVNC Unix viewer also supports x11vnc's symmetric |
| key encryption ciphers (see the 'UltraVNC DSM Encryption Plugin' |
| settings panel.) |
| |
| |
| Here are some features that will appear in the 0.9.13 release: |
| * Improved support for non-X11 touchscreen devices (e.g. handheld or |
| cell phone) via Linux uinput input injection. Additional tuning |
| parameters are added. TSLIB touchscreen calibration is supported. |
| Tested on Qtmoko Neo Freerunner. A tool, misc/uinput.pl, is |
| provided to diagnose uinput behavior on new devices. The env. |
| vars. X11VNC_UINPUT_BUS and X11VNC_UINPUT_VERSION are available if |
| leaving them unset does not work. |
| * The Linux uinput non-X11 input injection can now be bypassed: |
| events can be directly written to the /dev/input/event devices |
| specified by the user (direct_abs=..., etc.) A -pipeinput input |
| injection helper script, misc/qt_tslib_inject.pl is provided as a |
| tweakable non-builtin direct input injection method. |
| * The list of new uinput parameters for the above two features is: |
| pressure, tslib_cal, touch_always, dragskip, btn_touch; |
| direct_rel, direct_abs, direct_btn, direct_key. |
| * The MacOSX native server can now use OpenGL for the screen |
| capture. In nearly all cases this is faster than the raw |
| framebuffer capture method. There are build and run time flags, |
| X11VNC_MACOSX_NO_DEPRECATED, etc. to disable use of deprecated |
| input injection and screen access interfaces. Cursor shape now |
| works for 64bit binaries. |
| * The included SSL enabled Java VNC Viewers now handle Mouse Wheel |
| events. |
| * miscellaneous new features and changes: |
| * In -reflect mode, the libvncclient connection can now have the |
| pixel format modified via the environment variables |
| X11VNC_REFLECT_bitsPerSample, X11VNC_REFLECT_samplesPerPixel, and |
| X11VNC_REFLECT_bytesPerPixel |
| * In -create mode the following environment variables are added to |
| fine tune the behavior: FIND_DISPLAY_NO_LSOF: do not use lsof(1) |
| to try to determine the Linux VT, FIND_DISPLAY_NO_VT_FIND: do not |
| try to determine the Linux VT at all, X11VNC_CREATE_LC_ALL_C_OK: |
| do not bother undoing the setting LC_ALL=C that the create_display |
| script sets. The performance of the -create script has been |
| improved for large installations (100's of user sessions on one |
| machine.) |
| * In -unixpw mode, one can now Tab from login: to Password. |
| * An environment variable, X11VNC_SB_FACTOR, allows one to scale the |
| -sb screenblank sleep time from the default 2 secs. |
| * An experimental option -unixsock is available for testing. Note, |
| however, that it requires a manual change to |
| libvncserver/rfbserver.c for it to work. |
| * Documented that -grabkbd is no longer working with some/most |
| window managers (it can prevent resizing and menu posting.) |
| |
| |
| Here are some features that appeared in the 0.9.12 release (Sep/2010): |
| * One can now specify the maximum number of displays that can be |
| created in -create mode via the env. var. |
| X11VNC_CREATE_MAX_DISPLAYS |
| * The X11VNC_NO_LIMIT_SHM env. var. is added to skip any automatic |
| shared memory reduction. |
| * The kdm display manager is now detected when trying not to get |
| killed by the display manager. |
| * A compile time bug is fixed so that configuring using |
| --with-system-libvncserver pointing to LibVNCServer 0.9.7 works |
| again. A bug from forced use of Xdefs.h is worked around. |
| |
| |
| Here are some features that appeared in the 0.9.11 release (Aug/2010): |
| * The source tree is synchronized with the most recent libvncclient |
| (this only affects -reflect mode.) Build is fixed for |
| incompatibilities when using an external LibVNCServer (e.g. |
| ./configure --with-system-libvncserver...) Please help test these |
| build and runtime aspects and report back what you find, thanks. |
| * The SSL enabled Java VNC Viewer Makefile has been modified so that |
| the jar files that are built are compatible back to Java 1.4. |
| * In -create/-unixpw mode, the env. var. FD_USERPREFS may be set to |
| a filename in the user's home directory that includes default |
| username:options values (so the options do not need to be typed |
| every time at the login prompt.) |
| * In -reflect mode cursor position updates are now handled |
| correctly. |
| |
| |
| Here are some features that appeared in the 0.9.10 release (May/2010): |
| * The included SSL enabled Java applet viewer now supports Chained |
| SSL Certificates. The debugCerts=yes applet parameter aids |
| troubleshooting certificate validation. The x11vnc -ssl mode has |
| always supported chained SSL certificates (simply put the |
| intermediate certificates, in order, after the server certificate |
| in the pem file.) |
| * A demo CGI script desktop.cgi shows how to create an SSL |
| encrypted, multi-user x11vnc web login desktop service. The script |
| requires x11vnc version 0.9.10. The user logs into a secure web |
| site and gets his/her own virtual desktop (Xvfb.) x11vnc's SSL |
| enabled Java Viewer Applet is launched by the web browser for |
| secure viewing (and so no software needs to be installed on the |
| viewer-side.) One can use the desktop.cgi script for ideas to |
| create their own fancier or customized web login desktop service |
| (e.g. user-creation, PHP, SQL, specialized desktop application, |
| etc.) More info here. There is also an optional 'port redirection' |
| mode that allows redirection to other SSL enabled VNC servers |
| running inside the firewall. |
| * Built-in support for IPv6 (128 bit internet addresses) is now |
| provided. See the -6 and -connect options for details. |
| Additionally, in case there are still problems with built-in IPv6 |
| support, a transitional tool is provided in inet6to4 that allows |
| x11vnc (or any other IPv4 application) to receive connections over |
| IPv6. |
| * The Xdummy wrapper script for Xorg's dummy driver is updated and |
| no longer requires being run as root. New service options are |
| provided to select Xdummy over Xvfb as the virtual X server to be |
| created. |
| * The "%" unix password verification tricks for the -unixpw option |
| are now documented. They have also been extended to run a command |
| as the user if one sets the environment variable UNIXPW_CMD. The |
| desktop.cgi demo script takes advantage of this new feature. |
| * A bug has been fixed that would prevent the Java applet viewer |
| from being downloaded successfully in single-port HTTPS/VNC inetd |
| mode. The env. var. X11VNC_HTTPS_DOWNLOAD_WAIT_TIME can be used to |
| adjust for how many seconds a -inetd or -https httpd download is |
| waited for (default 15 seconds.) The applet will now autodetect |
| x11vnc and use GET=1 for faster connecting. Many other |
| improvements and fixes. |
| * The TightVNC security type (TightVNC features enabler) now works |
| for RFB version 3.8. |
| * The X property X11VNC_TRAP_XRANDR can be set on a desktop to force |
| x11vnc to use the -xrandr screen size change trapping code. |
| * New remote control query options: pointer_x, pointer_y, |
| pointer_same, pointer_root, and pointer_mask. A demo script using |
| them misc/panner.pl is provided. |
| * The -sslScripts option prints out the SSL certificate management |
| scripts. |
| |
| |
| Here are some features that appeared in the 0.9.9 release (Dec/2009): |
| * The -unixpw_system_greeter option, when used in combined unixpw |
| and XDMCP FINDCREATEDISPLAY mode (for example: -xdmsvc), enables |
| the user to press Escape to jump directly to the XDM/GDM/KDM login |
| greeter screen. This way the user avoids entering his unix |
| password twice at X session creation time. Also, the unixpw login |
| panel now has a short help displayed if the user presses 'F1'. |
| * x11vnc now tries to be a little bit more aggressive in keeping up |
| with VNC client's framebuffer update requests. Some broken VNC |
| clients like Eggplant and JollysFastVNC continuously spray these |
| requests at VNC servers (regardless of whether they have received |
| any updates or not.) Under some circumstances this could lead to |
| x11vnc falling behind. The -extra_fbur option allows one to fine |
| tune the setting. Additionally, one may also dial down delays: |
| e.g. "-defer 5" and "-wait 5" (or to 1 or even 0) or -nonap or |
| -allinput to keep up with these VNC clients at the expense of |
| increased system load. |
| * Heuristics are applied to try to determine if the X display is |
| currently in a Display Manager Greeter Login panel (e.g. GDM) If |
| so, x11vnc's creation of any windows and use of XFIXES are |
| delayed. This is to try to avoid x11vnc being killed after the |
| user logs in if the GDM KillInitClients=true is in effect. So one |
| does not need to set KillInitClients=false. Note that in recent |
| GDM the KillInitClients option has been removed. Also delayed is |
| the use of the XFIXES cursor fetching functionality; this avoids |
| an Xorg bug that causes Xorg to crash right after the user logs |
| in. |
| * A new option -findauth runs the FINDDISPLAY script that applies |
| heuristics that try to determine the XAUTHORITY file. The use of |
| '-auth guess' will use the XAUTHORITY that -findauth reveals. This |
| can be handy in with the lastest GDM where the ability to store |
| cookies in ~/.Xauthority has been removed. If x11vnc is running as |
| root (e.g. inetd) and you add -env FD_XDM=1 to the above -findauth |
| or -auth guess command lines, it will find the correct XAUTHORITY |
| for the given display (this works for XDM/GDM/KDM if the login |
| greeter panel is up or if someone has already logged into an X |
| session.) |
| * The FINDDISPLAY and FINDCREATEDISPLAY modes (i.e. "-display |
| WAIT:cmd=...", -find, -create) now work correctly for the |
| user-supplied login program scheme "-unixpw_cmd ...", as long as |
| the login program supports running commands specified in the |
| environment variable "RFB_UNIXPW_CMD_RUN" as the logged-in user. |
| The mode "-unixpw_nis ..." has also been made more consistent. |
| * The -stunnel option (like -ssl but uses stunnel as an external |
| helper program) now works with the -ssl "SAVE" and "TMP" special |
| certificate names. The -sslverify and -sslCRL options now work |
| correctly in -stunnel mode. Single port HTTPS connections are also |
| supported for this mode. |
| * There is an experimental Application Sharing mode that improves |
| upon the -id/-sid single window sharing: -appshare (run "x11vnc |
| -appshare -help" for more info.) It is still very primitive and |
| approximate, but at least it displays multiple top-level windows. |
| * The remote control command -R can be used to instruct x11vnc to |
| resend its most recent copy of the Clipboard, Primary, or |
| Cutbuffer selections: "x11vnc -R resend_clipboard", "x11vnc -R |
| resend_primary", and "x11vnc -R resend_cutbuffer". |
| * The fonts in the GUI (-gui) can now by set via environment |
| variables, e.g. -env X11VNC_FONT_BOLD='Helvetica -16 bold' and |
| -env X11VNC_FONT_FIXED='Courier -14'. |
| * The XDAMAGE mechanism is now automatically disabled for a period |
| of time if a game or screensaver generates too many XDAMAGE |
| rectangles per second. This avoids the X11 event queue from |
| soaking up too much memory. |
| * There is an experimental workaround: "-env X11VNC_WATCH_DX_DY=1" |
| that tries to avoid problems with poorly constructed menu themes |
| that place the initial position of the mouse cursor inside a menu |
| item's active zone. More information can be found here. |
| |
| |
| Here are some features that appeared in the 0.9.8 release (Jul/2009): |
| * Stability improvements to -threads mode. Running x11vnc this way |
| is more reliable now. Threaded operation sometimes gives better |
| interactive response and faster updates: try it out. The threaded |
| mode now supports multiple VNC viewers using the same VNC |
| encoding. The threaded mode can also yield a performance |
| enhancement in the many client case (e.g. class-room broadcast.) |
| We have tested with 30 to 50 simultaneous clients. See also |
| -reflect. |
| For simultaneous clients: the ZRLE encoding is thread safe on all |
| platforms, and the Tight and Zlib encodings are currently only |
| thread safe on Linux where thread local storage, __thread, is |
| used. If your non-Linux system and compiler support __thread one |
| can supply -DTLS=__thread to enable it. When there is only one |
| connected client, all encodings are safe on all platforms. Note |
| that some features (e.g. scroll detection and -ncache) may be |
| disabled or run with reduced functionality in -threads mode. |
| * Automatically tries to work around an Xorg server and GNOME bug |
| involving infinitely repeating keys when turning off key |
| repeating. Use -repeat if the automatic workaround fails. |
| * Improved reliability of the Single Port SSL VNC and HTTPS java |
| viewer applet delivery mechanism. |
| * The -clip mode works under -rawfb. |
| |
| |
| Here are some features that appeared in the 0.9.7 release (Mar/2009): |
| * Support for polling Linux Virtual Terminals (also called virtual |
| consoles) directly instead of using /dev/fb. The option to use is, |
| for example, "-rawfb vt2" for Virtual Terminal 2, etc. In this |
| case the special file /dev/vcsa2 is used to retrieve vt2's current |
| text. Text and colors are shown, but no graphics. |
| * Support for less than 8 bits per pixel framebuffers (e.g. 4 or 1 |
| bpp) in the -rawfb mode. |
| * The SSL enabled UltraVNC Java viewer applet now has a [Home] entry |
| in the "drives" drop down menu. This menu can be configured with |
| the ftpDropDown applet parameter. All of the applet parameters are |
| documented in classes/ssl/README. |
| * Experimental support for VirtualGL's TurboVNC (an enhanced |
| TightVNC for fast LAN high framerate usage.) |
| * The CUPS Terminal Services helper mode has been improved. |
| * Improvements to the -ncache_cr that allows smooth opaque window |
| motions using the 'copyrect' encoding when using -ncache mode. |
| * The -rmflag option enables a way to indicate to other processes |
| x11vnc has exited. |
| * Reverse connections using anonymous Diffie Hellman SSL encryption |
| now work. |
| |
| |
| Here are some features that appeared in the 0.9.6 release (Dec/2008): |
| * Support for VeNCrypt SSL/TLS encrypted connections. It is enabled |
| by default in the -ssl mode. VNC Viewers like vinagre, |
| gvncviewer/gtk-vnc, the vencrypt package, SSVNC, and others |
| support this encryption mode. It can also be used with the -unixpw |
| option to enable Unix username and password authentication |
| (VeNCrypt's "*Plain" modes.) A similar but older VNC security type |
| "ANONTLS" (used by vino) is supported as well. See the -vencrypt |
| and -anontls options for additional control. The difference |
| between x11vnc's normal -ssl mode and VeNCrypt is that the former |
| wraps the entire VNC connection in SSL (like HTTPS does for HTTP, |
| i.e. "vncs://") while VeNCrypt switches on the SSL/TLS at a |
| certain point during the VNC handshake. Use -sslonly to disable |
| both VeNCrypt and ANONTLS (vino.) |
| * The "-ssl ANON" option enables Anonymous Diffie-Hellman (ADH) key |
| exchange for x11vnc's normal SSL/TLS operation. Note that |
| Anonymous Diffie-Hellman uses encryption for privacy, but provides |
| no authentication and so is susceptible to Man-In-The-Middle |
| attacks (and so we do not recommend it: we prefer you use "-ssl |
| SAVE", etc. and have the VNC viewer verify the cert.) The ANONTLS |
| mode (vino) only supports ADH. VeNCrypt mode supports both ADH and |
| regular X509 SSL certificates modes. For these ADH is enabled by |
| default. See -vencrypt and -anontls for how to disable ADH. |
| * For x11vnc's SSL/TLS modes, one can now specify a Certificate |
| Revocation List (CRL) with the -sslCRL option. This will only be |
| useful for wide deployments: say a company-wide x11vnc SSL access |
| deployment using a central Certificate Authority (CA) via |
| -sslGenCA and -sslGenCert. This way if a user has his laptop lost |
| or stolen, you only have to revoke his key instead of creating a |
| new Certificate Authority and redeploying new keys to all users. |
| * The default SSL/TLS mode, "-ssl" (no pem file parameter supplied), |
| is now the same as "-ssl SAVE" and will save the generated |
| self-signed cert in "~/.vnc/certs/server.pem". Previously "-ssl" |
| would create a temporary self-signed cert that was discarded when |
| x11vnc exited. The reason for the change is to at least give the |
| chance for the VNC Viewer side (e.g. SSVNC) to remember the cert |
| to authenticate subsequent connections to the same x11vnc server. |
| Use "-ssl TMP" to regain the previous behavior. Use "-ssl |
| SAVE_NOPROMPT" to avoid being prompted about using passphrase when |
| the certificate is created. |
| * The option -http_oneport enables single-port HTTP connections via |
| the Java VNC Viewer. So, for example, the web browser URL |
| "http://myhost.org:5900" works the same as |
| "http://myhost.org:5800", but with the convenience of only |
| involving one port instead of two. This works for both unencrypted |
| connections and for SSH tunnels (see -httpsredir if the tunnel |
| port differs.) Note that HTTPS single-port operation in -ssl SSL |
| encrypted mode has been available since x11vnc version 0.8.3. |
| * For the -avahi/-zeroconf Service Advertizing mode, if x11vnc was |
| not compiled with the avahi-client library, then an external |
| helper program, either avahi-publish(1) (on Unix) or dns-sd(1) (on |
| Mac OS X), is used instead. |
| * The "-rfbport PROMPT" option will prompt the user via the GUI to |
| select the VNC port (e.g. 5901) to listen on, and a few other |
| basic settings. This enables a handy GUI mode for naive users: |
| x11vnc -gui tray=setpass -rfbport PROMPT -logfile $HOME/.x11vnc.log.%VNCDISP |
| LAY |
| suitable for putting in a launcher or menu, e.g. x11vnc.desktop. |
| The -logfile expansion is new too. In the GUI, the tray=setpass |
| Properties panel has been improved. |
| * The -solid solid background color option now works for the Mac OS |
| X console. |
| * The -reopen option instructs x11vnc to try to reopen the X display |
| if it is prematurely closed by, say, the display manager (e.g. |
| GDM.) |
| |
| |
| Here are some features that appeared in the 0.9.5 release (Oct/2008): |
| * Symmetric key encryption ciphers. ARC4, AES-128, AES-256, |
| blowfish, and 3des are supported. Salt and initialization vector |
| seeding is provided. These compliment the more widely used SSL and |
| SSH encryption access methods. SSVNC also supports these |
| encryption modes. |
| * Scaling differently along the X- and Y-directions. E.g. "-scale |
| 1280x1024" or "-scale 0.8x0.75" Also, "-geometry WxH" is an |
| alias for "-scale WxH" |
| * By having SSVNC version 1.0.21 or later available in your $PATH, |
| the -chatwindow option allows a UltraVNC Text Chat window to |
| appear on the local X11 console/display (this way the remote |
| viewer can chat with the person at the physical display; e.g. |
| helpdesk mode.) This also works on the Mac OS X console if the |
| Xquartz X11 server (enabled by default on leopard) is running for |
| the chatwindow. |
| * The HTTP Java viewer applet jar, classes/VncViewer.jar, has been |
| updated with an improved implementation based on the code used by |
| the classes/ssl applets. |
| |
| |
| Here are some features that appeared in the 0.9.4 release (Sep/2008): |
| * Improvements to the -find and -create X session finding or |
| creating modes: new desktop types and service redirection options. |
| Personal cupsd daemon and SSH port redirection helper for use with |
| SSVNC's Terminal Services feature. |
| * Reverse VNC connections via -connect work in the -find, -create |
| and related -display WAIT:... modes. |
| * Reverse VNC connections (either normal or SSL) can use a Web Proxy |
| or a SOCKS proxy, or a SSH connection, or even a CGI URL to make |
| the outgoing connection. See: -proxy. Forward connections can also |
| use: -ssh. |
| * Reverse VNC connections via the UltraVNC repeater proxy (either |
| normal or SSL) are supported. Use either the "-connect |
| repeater=ID:NNNN+host:port" or "-connect |
| repeater://host:port+ID:NNNN" notation. The SSVNC VNC viewer also |
| supports the UltraVNC repeater. Also, a perl repeater implemention |
| is here: ultravnc_repeater.pl |
| * Support for indexed colormaps (PseudoColor) with depths other than |
| 8 (from 1 to 16 now work) for non-standard hardware. Option |
| "-advertise_truecolor" to handle some workaround in this mode. |
| * Support for the ZYWRLE encoding, this is the RealVNC ZRLE encoding |
| extended to do motion video and photo regions more efficiently by |
| way of a Wavelet based transformation. |
| * The -finddpy and -listdpy utilities help to debug and configure |
| the -find, -create, and -display WAIT:... modes. |
| * Some automatic detection of screen resizes are handled even if the |
| -xrandr option is not supplied. |
| * The -autoport options gives more control over the VNC port x11vnc |
| chooses. |
| * The -ping secs can be used to help keep idle connections alive. |
| * Pasting of the selection/clipboard into remote applications (e.g. |
| Java) has been improved. |
| * Fixed a bug if a client disconnects during the 'speed-estimation' |
| phase. |
| * To unset Caps_Lock, Num_Lock and raise all keys in the X server |
| use -clear_all. |
| * Usage with dvorak keyboards has been improved. See also: -xkb. |
| * The Java Viewer applet source code is now included in the |
| x11vnc-0.9.*.tar.gz tarball. This means you can now build the Java |
| viewer applet jar files from source. If you stopped shipping the |
| Java viewer applet jar files due to lack of source code, you can |
| start again. |
| |
| |
| Here are some features that appeared in the 0.9.3 release (Oct/2007): |
| * Viewer-side pixmap caching. A large area of pixels (at least 2-3 |
| times as big as the framebuffer itself; the bigger the better... |
| default is 10X) is placed below the framebuffer to act as a |
| buffer/cache area for pixel data. The VNC CopyRect encoding is |
| used to move it around, so any viewer can take advantage of it. |
| Until we start modifying viewers you will be able to see the cache |
| area if you scroll down (this makes it easier to debug!) For |
| testing the default is "-ncache 10". The unix Enhanced TightVNC |
| Viewer ssvnc has a nice -ycrop option to help hide the pixel cache |
| area from view. |
| |
| |
| Here are some features that appeared in the 0.9.2 release (Jun/2007): |
| * Building with no OpenSSL libssl available (or with --without-ssl) |
| has been fixed. |
| * One can configure x11vnc via "./configure |
| --with-system-libvncserver" to use a system installed libvncserver |
| library instead of the one bundled in the release tarball. |
| * If UltraVNC file transfer or chat is detected, then VNC clients |
| are "pinged" more often to prevent these side channels from |
| becoming serviced too infrequently. |
| * In -unixpw mode in the username and password dialog no text will |
| be echoed if the first character sent is "Escape". This enables a |
| convenience feature in SSVNC to send the username and password |
| automatically. |
| |
| |
| Here are some features that appeared in the 0.9.1 release (May/2007): |
| * The UltraVNC Java viewer has been enhanced to support SSL (as the |
| TightVNC viewer had been previously.) The UltraVNC Java supports |
| ultravnc filetransfer, and so can be used as a VNC viewer on Unix |
| that supports ultravnc filetransfer. It is in the |
| classes/ssl/UltraViewerSSL.jar file (that is pointed to by |
| ultra.vnc.) The signed applet SignedUltraViewerSSL.jar version |
| (pointed to by ultrasigned.vnc) will be needed to access the local |
| drive if you are using it for file transfer via a Web browser. |
| Some other bugs in the UltraVNC Java viewer were fixed and a few |
| improvements to the UI made. |
| * A new Unix username login mode for VNC Viewers authenticated via a |
| Client SSL Certificate: "-users sslpeer=". The emailAddress |
| subject field is inspected for username@hostname and then acts as |
| though "-users +username" has been supplied. This way the Unix |
| username is identified by (i.e. simply extracted from) the Client |
| SSL Certificate. This could be useful with -find, -create and -svc |
| modes if you are also have set up and use VNC Client SSL |
| Certificate authentication. |
| * For external display finding/creating programs (e.g. WAIT:cmd=...) |
| if the VNC Viewer is authenticated via a Client SSL Certificate, |
| then that Certificate is available in the environment variable |
| RFB_SSL_CLIENT_CERT. |
| |
| |
| Here are some features that appeared in the 0.9 release (Apr/2007): |
| * VNC Service advertising via mDNS / ZeroConf / BonJour with the |
| Avahi client library. Enable via "-avahi" or "-zeroconf". |
| * Implementations of UltraVNC's TextChat, SingleWindow, and |
| ServerInput extensions (requires ultravnc viewer or ssvnc Unix |
| viewer.) They toggle the selection of a single window (-id), and |
| disable (friendly) user input and viewing (monitor blank) at the |
| VNC server. |
| * Short aliases "-find", "-create", "-svc", and "-xdmsvc" for |
| commonly used FINDCREATEDISPLAY usage modes. |
| * Reverse VNC connections (viewer listening) now work in SSL (-ssl) |
| mode. |
| * New options to control the Monitor power state and keyboard/mouse |
| grabbing: -forcedpms, -clientdpms, -noserverdpms, and -grabalways. |
| * A simple way to emulate inetd(8) to some degree via the "-loopbg" |
| option. |
| * Monitor the accuracy of XDAMAGE and apply "-noxdamage" if it is |
| not working well. OpenGL applications like like beryl and MythTv |
| have been shown to make XDAMAGE not work properly. |
| * For Java SSL connections involving a router/firewall port |
| redirection, an option -httpsredir to spare the user from needing |
| to include &PORT=NNN in the browser URL. |
| |
| |
| Here are some features that appeared in the 0.8.4 release (Feb/2007): |
| * Native Mac OS X Aqua/Quartz support. (i.e. OSXvnc alternative; |
| some activities are faster) |
| * A new login mode: "-display WAIT:cmd=FINDCREATEDISPLAY -unixpw |
| ..." that will Create a new X session (either virtual or real and |
| with or without a display manager, e.g. kdm) for the user if it |
| cannot find the user's X session display via the FINDDISPLAY |
| method. See the -svc and the -xdmsvc aliases. |
| * x11vnc can act as a VNC reflector/repeater using the "-reflect |
| host:N" option. Instead of polling an X display, the remote VNC |
| Server host:N is connected to and re-exported via VNC. This is |
| intended for use in broadcasting a display to many (e.g. > 16; |
| classroom or large demo) VNC viewers where bandwidth and other |
| resources are conserved by spreading the load over a number of |
| repeaters. |
| * Wireframe copyrect detection for local user activity (e.g. someone |
| sitting at the physical display moving windows) Use |
| -nowireframelocal to disable. |
| * The "-N" option couples the VNC Display number to the X Display |
| number. E.g. if your X DISPLAY is :2 then the VNC display will be |
| :2 (i.e. using port 5902.) If that port is taken x11vnc will exit. |
| * Option -nodpms to avoid problems with programs like KDE's |
| kdesktop_lock that keep restarting the screen saver every few |
| seconds. |
| * To automatically fix the common mouse motion problem on XINERAMA |
| (multi-headed) displays, the -xwarppointer option is enabled by |
| default when XINERAMA is active. |
| |
| If you have a Mac please try out the native Mac OS X support, build |
| with "./configure --without-x", or download a binary mentioned above, |
| (even if you don't plan on ever using it in this mode!), and let me |
| know how it went. Thanks. |
| |
| |
| Here are some features that appeared in the 0.8.3 release (Nov/2006): |
| * The -ssl option provides SSL encryption and authentication |
| natively via the www.openssl.org library. One can use from a |
| simple self-signed certificate server certificate up to full CA |
| and client certificate authentication schemes. |
| * Similar to -ssl, the -stunnel option starts up a SSL tunnel server |
| stunnel (that must be installed separately on the system: |
| stunnel.mirt.net ) to allow only encrypted SSL connections from |
| the network. |
| * The -sslverify option allows for authenticating VNC clients via |
| their certificates in either -ssl or -stunnel modes. |
| * Certificate creation and management tools are provide in the |
| -sslGenCert, -sslGenCA, and related options. |
| * An SSL enabled Java applet VNC Viewer applet is provided by x11vnc |
| in classes/ssl/VncViewer.jar. In addition to normal HTTP, the |
| applet may be loaded into the web browser via HTTPS (HTTP over |
| SSL.) (one can use the VNC port, e.g. https://host:5900/, or also |
| the separate -https port option.) A wrapper shell script |
| ss_vncviewer is also provided that sets up a stunnel client-side |
| tunnel on Unix systems. See Enhanced TightVNC Viewer (SSVNC) for |
| other SSL/SSH viewer possibilities. |
| * The -unixpw option supports Unix username and password |
| authentication (a simpler variant is the -unixpw_nis option that |
| works in environments where the encrypted passwords are readable, |
| e.g. NIS.) The -ssl or -localhost + -stunnel options are enforced |
| in this mode to prevent password sniffing. As a convenience, these |
| requirements are lifted if a SSH tunnel can be deduced (but |
| -localhost still applies.) |
| * Coupling -unixpw with "-display WAIT:cmd=FINDDISPLAY" or "-display |
| WAIT:cmd=FINDCREATEDISPLAY" provides a way to allow a user to |
| login with their UNIX password and have their display connected to |
| automatically. See the -svc and the -xdmsvc aliases. |
| * Hooks are provided in the -unixpw_cmd and "-passwdfile |
| cmd:,custom:..." options to allow you to supply your own |
| authentication and password lookup programs. |
| * x11vnc can be configured and built to not depend on X11 libraries |
| "./configure --without-x" for -rawfb only operation (e.g. embedded |
| linux console devices.) |
| * The -rotate option enables you to rotate or reflect the screen |
| before exporting via VNC. This is intended for use on handhelds |
| and other devices where the rotation orientation is not "natural". |
| * The "-ultrafilexfer" alias is provided and improved UltraVNC |
| filetransfer rates have been achieved. |
| * Under the "-connect_or_exit host" option x11vnc will exit |
| immediately unless the reverse connection to host succeeds. The |
| "-rfbport 0" option disables TCP listening for connections (useful |
| for this mode.) |
| * The "-rawfb rand" and "-rawfb none" options are useful for testing |
| automation scripts, etc., without requiring a full desktop. |
| * Reduced spewing of information at startup, use "-verbose" (also |
| "-v") to turn it back on for debugging or if you are going to send |
| me a problem report. |
| |
| Here are some Previous Release Notes |
| _________________________________________________________________ |
| |
| Some Notes: |
| |
| Both a client and a server: It is sometimes confusing to people that |
| x11vnc is both a client and a server at the same time. It is an X |
| client because it connects to the running X server to do the screen |
| polls. Think of it as a rather efficient "screenshot" program running |
| continuously. It is a server in the sense that it is a VNC server that |
| VNC viewers on the network can connect to and view the screen |
| framebuffer it manages. |
| |
| When trying to debug problems, remember to think of both roles. E.g. |
| "how is x11vnc connecting to the X server?", "how is the vncviewer |
| connecting to x11vnc?", "what permits/restricts the connection?". Both |
| links may have reachability, permission, and other issues. |
| |
| Network performance: Whether you are using Xvnc or x11vnc it is |
| always a good idea to have a solid background color instead of a |
| pretty background image. Each and every re-exposure of the background |
| must be resent over the network: better to have that background be a |
| solid color that compresses very well compared to a photo image. (This |
| is one place where the X protocol has an advantage over the VNC |
| protocol.) I suggest using xsetroot, dtstyle or similar utility to set |
| a solid background while using x11vnc. You can turn the pretty |
| background image back on when you are using the display directly. |
| Update: As of Feb/2005 x11vnc has the -solid [color] option that works |
| on recent GNOME, KDE, and CDE and also on classic X (background image |
| is on the root window.) Update: As of Oct/2007 x11vnc has the -ncache |
| option that does a reasonable job caching the background (and other) |
| pixmap data on the viewer side. |
| |
| I also find the TightVNC encoding gives the best response for my usage |
| (Unix <-> Unix over cable modem.) One needs a tightvnc-aware vncviewer |
| to take advantage of this encoding. |
| |
| TCP port issues: Notice the lines |
| 18/07/2003 14:36:31 Autoprobing selected port 5900 |
| PORT=5900 |
| |
| in the output. 5900 is the default VNC listening port (just like 6000 |
| is X11's default listening port.) Had port 5900 been taken by some |
| other application, x11vnc would have next tried 5901. That would mean |
| the viewer command above should be changed to vncviewer |
| far-away.east:1. You can force the port with the "-rfbport NNNN" |
| option where NNNN is the desired port number. If that port is already |
| taken, x11vnc will exit immediately. The "-N" option will try to match |
| the VNC display number to the X display. (also see the "SunRay |
| Gotcha" note below) |
| |
| Options: x11vnc has (far too) many features that may be activated |
| via its command line options. Useful options are, e.g., -scale to do |
| server-side scaling, and -rfbauth passwd-file to use VNC password |
| protection (the vncpasswd or storepasswd programs, or the x11vnc |
| -storepasswd option can be used to create the password file.) |
| |
| Algorithm: How does x11vnc do it? Rather brute-forcedly: it |
| continuously polls the X11 framebuffer for changes using |
| XShmGetImage(). When changes are discovered, it instructs libvncserver |
| which rectangular regions of the framebuffer have changed, and |
| libvncserver compresses the changes and sends them off to any |
| connected VNC viewers. A number of applications do similar things, |
| such as x0rfbserver, krfb, x0vncserver, vino. x11vnc uses a 32 x 32 |
| pixel tile model (the desktop is decomposed into roughly 1000 such |
| tiles), where changed tiles are found by pseudo-randomly polling 1 |
| pixel tall horizontal scanlines separated vertically by 32 pixels. |
| This is a surprisingly effective algorithm for finding changed |
| regions. For keyboard and mouse user input the XTEST extension is used |
| to pass the input events to the X server. To detect XBell "beeps" the |
| XKEYBOARD extension is used. If available, the XFIXES extension is |
| used to retrieve the current mouse cursor shape. Also, if available |
| the X DAMAGE extension is used to receive hints from the X server |
| where modified regions on the screen are. This greatly reduces the |
| system load when not much is changing on the screen and also improves |
| how quickly the screen is updated. |
| |
| Barbershop mirrors effect: What if x11vnc is started up, and |
| vncviewer is then started up on the same machine and displayed on the |
| same display x11vnc is polling? One might "accidentally" do this when |
| first testing out the programs. You get an interesting |
| recursive/feedback effect where vncviewer images keep popping up each |
| one contained in the previous one and slightly shifted a bit by the |
| window manager decorations. There will be an even more interesting |
| effect if -scale is used. Also, if the XKEYBOARD is supported and the |
| XBell "beeps" once, you get an infinite loop of beeps going off. |
| Although all of this is mildly exciting it is not much use: you will |
| normally run and display the viewer on a different machine! |
| _________________________________________________________________ |
| |
| Sun Ray Notes: |
| |
| You can run x11vnc on your (connected or disconnected) SunRay session. |
| Here are some notes on SunRay usage with x11vnc. |
| |
| _________________________________________________________________ |
| |
| Limitations: |
| |
| * Due to the polling nature, some activities (opaque window moves, |
| scrolling), can be pretty choppy/ragged and others (exposures of |
| large areas) slow. Experiment with interacting a bit differently |
| than you normally do to minimize the effects (e.g. do fullpage |
| paging rather than line-by-line scrolling, and move windows in a |
| single, quick motion.) Recent work has provided the |
| -scrollcopyrect and -wireframe speedups using the CopyRect VNC |
| encoding and other things, but they only speed up some activities, |
| not all. |
| * A rate limiting factor for x11vnc performance is that graphics |
| hardware is optimized for writing, not reading (x11vnc reads the |
| video framebuffer for the screen image data.) The difference can |
| be a factor of 10 to 1000, and so it usually takes about 0.5-1 sec |
| to read in the whole video hardware framebuffer (e.g. 5MB for |
| 1280x1024 at depth 24 with a read rate of 5-10MB/sec.) So whenever |
| activity changes most of the screen (e.g. moving or iconifying a |
| large window) there is a delay of 0.5-1 sec while x11vnc reads the |
| changed regions in. |
| A slow framebuffer read rate will often be the performance |
| bottleneck on a fast LAN (whereas on slower links the reduced |
| network bandwidth becomes the bottleneck.) |
| Note: A quick way to get a 2X speedup of this for x11vnc is to |
| switch your X server from depth 24 (32bpp) to depth 16 (16bpp.) |
| You get a 4X speedup going to 8bpp, but the lack of color cells is |
| usually unacceptable. |
| To get a sense of the read and write speeds of your video card, |
| you can run benchmarks like: "x11perf -getimage500", "x11perf |
| -putimage500", "x11perf -shmput500" and for XFree86 displays with |
| direct graphics access the "dga" command (press "b" to run the |
| benchmark and then after a few seconds press "q" to quit.) Even |
| this "dd if=/dev/fb0 of=/dev/null" often gives a good estimate. |
| x11vnc also prints out its estimate: |
| 28/02/2009 11:11:07 Autoprobing TCP port |
| 28/02/2009 11:11:07 Autoprobing selected port 5900 |
| 28/02/2009 11:11:08 fb read rate: 10 MB/sec |
| 28/02/2009 11:11:08 screen setup finished. |
| We have seen a few cases where the hardware fb read speed is |
| greater than 65 MB/sec: on high end graphics workstations from SGI |
| and Sun, and also from a Linux user using nvidia proprietary |
| drivers for his nvidia video card. Update 2008: thankfully, these |
| sped up drivers are becoming more common on Linux and *BSD systems |
| and that makes x11vnc run somewhat more quickly. Sometimes they |
| have a read rate of over 400 MB/sec. |
| On XFree86/Xorg it is actually possible to increase the |
| framebuffer read speed considerably (10-100 times) by using the |
| Shadow Framebuffer (a copy of the framebuffer is kept in main |
| memory and this can be read much more quickly.) To do this one |
| puts the line Option "ShadowFB" "true" in the Device section of |
| the /etc/X11/XF86Config or /etc/X11/xorg.conf file. Note that this |
| disables 2D acceleration at the physical display and so that might |
| be unacceptable if one plays games, etc. on the machine's local |
| display. Nevertheless this could be handy in some circumstances, |
| e.g. if the slower speed while sitting at the physical display was |
| acceptable (this seems to be true for most video cards these |
| days.) Unfortunately it does not seem shadowfb can be turned on |
| and off dynamically... |
| Another amusing thing one can do is use Xvfb as the X server, e.g. |
| "xinit $HOME/.xinitrc -- /usr/X11R6/bin/Xvfb :1 -screen 0 |
| 1024x768x16" x11vnc can poll Xvfb efficiently via main memory. |
| It's not exactly clear why one would want to do this instead of |
| using vncserver/Xvnc, (perhaps to take advantage of an x11vnc |
| feature, such as framebuffer scaling or built-in SSL encryption), |
| but we mention it because it may be of use for special purpose |
| applications. You may need to use the "-cc 4" option to force Xvfb |
| to use a TrueColor visual instead of DirectColor. See also the |
| description of the -create option that does all of this |
| automatically for you (be sure to install the Xvfb package, e.g. |
| apt-get install xvfb.) |
| Also, a faster and more accurate way is to use the "dummy" |
| Xorg/XFree86 device driver (or our Xdummy wrapper script.) See |
| this FAQ for details. |
| * Somewhat surprisingly, the X11 mouse (cursor) shape is write-only |
| and cannot be queried from the X server. So traditionally in |
| x11vnc the cursor shape stays fixed at an arrow. (see the "-cursor |
| X" and "-cursor some" options, however, for a partial hack for the |
| root window, etc.) However, on Solaris using the SUN_OVL overlay |
| extension, x11vnc can show the correct mouse cursor when the |
| -overlay option is also supplied. A similar thing is done on IRIX |
| as well when -overlay is supplied. |
| More generally, as of Dec/2004 x11vnc supports the new XFIXES |
| extension (in Xorg and Solaris 10) to query the X server for the |
| exact cursor shape, this works pretty well except that cursors |
| with transparency (alpha channel) need to approximated to solid |
| RGB values (some cursors look worse than others.) |
| * Audio from applications is of course not redirected (separate |
| redirectors do exist, e.g. esd, see the FAQ on this below.) The |
| XBell() "beeps" will work if the X server supports the XKEYBOARD |
| extension. (Note that on Solaris XKEYBOARD is disabled by default. |
| Passing +kb to Xsun enables it.) |
| * The scroll detection algorithm for the -scrollcopyrect option can |
| give choppy or bunched up transient output and occasionally |
| painting errors. |
| * Using -threads can expose some bugs/crashes in libvncserver. |
| |
| Please feel free to contact me if you have any questions, problems, or |
| comments about x11vnc, etc. Please be polite, thorough, and not |
| demanding (sadly, the number of people contacting me that are rude and |
| demanding is increasing dramatically.) |
| Also, some people ask if they can make a donation, see this link for |
| that. |
| |
| ======================================================================= |
| http://www.karlrunge.com/x11vnc/faq.html: |
| |
| |
| x11vnc Home Donations |
| _________________________________________________________________ |
| |
| x11vnc FAQ: |
| |
| |
| [Building and Starting] |
| |
| Q-1: I can't get x11vnc to start up. It says "XOpenDisplay failed |
| (null)" or "Xlib: connection to ":0.0" refused by server Xlib: No |
| protocol specified" and then exits. What do I need to do? |
| |
| Q-2: I can't get x11vnc and/or libvncserver to compile. |
| |
| Q-3: I just built x11vnc successfully, but when I use it my keystrokes |
| and mouse button clicks are ignored (I am able to move the mouse |
| though.) |
| |
| Q-4: Help, I need to run x11vnc on Solaris 2.5.1 (or other old |
| Unix/Linux) and it doesn't compile! |
| |
| Q-5: Where can I get a precompiled x11vnc binary for my Operating |
| System? |
| |
| Q-6: Where can I get a VNC Viewer binary (or source code) for the |
| Operating System I will be viewing from? |
| |
| Q-7: How can I see all of x11vnc's command line options and |
| documentation on how to use them? |
| |
| Q-8: I don't like typing arcane command line options every time I |
| start x11vnc. What can I do? Is there a config file? Or a GUI? |
| |
| Q-9: How can I get the GUI to run in the System Tray, or at least be a |
| smaller, simpler icon? |
| |
| Q-10: How can I get x11vnc to listen on a different port besides the |
| default VNC port (5900)? |
| |
| Q-11: My Firewall/Router doesn't allow VNC Viewers to connect to |
| x11vnc. |
| |
| Q-12: Is it possible for a VNC Viewer and a VNC Server to connect to |
| each other even though both are behind Firewalls that block all |
| incoming connections? |
| |
| Q-13: Can I make x11vnc more quiet and also go into the background |
| after starting up? |
| |
| Q-14: Sometimes when a VNC viewer dies abruptly, x11vnc also dies with |
| the error message like: "Broken pipe". I'm using the -forever mode and |
| I want x11vnc to keep running. |
| |
| Q-15: The Windows TightVNC 1.3.9 Viewer cannot connect to x11vnc. |
| |
| Q-16: KDE's krdc VNC viewer cannot connect to x11vnc. |
| |
| Q-17: When I start x11vnc on an Alpha Tru64 workstation the X server |
| crashes! |
| |
| Q-18: When running x11vnc on an IBM AIX workstation after a few |
| minutes the VNC connection freezes. |
| |
| Q-19: Are there any build-time customizations possible, e.g. change |
| defaults, create a smaller binary, etc? |
| |
| [Win2VNC Related] |
| |
| Q-20: I have two separate machine displays in front of me, one Windows |
| the other X11: can I use x11vnc in combination with Win2VNC in |
| dual-screen mode to pass the keystrokes and mouse motions to the X11 |
| display? |
| |
| Q-21: I am running Win2VNC on my Windows machine and "x11vnc -nofb" on |
| Unix to pass keyboard and mouse to the Unix monitor. Whenever I start |
| Win2VNC it quickly disconnects and x11vnc says: |
| rfbProcessClientNormalMessage: read: Connection reset by peer |
| |
| Q-22: Can I run "x11vnc -nofb" on a Mac OS X machine to redirect mouse |
| and keyboard input to it from Windows and X11 machines via Win2VNC and |
| x2vnc, respectively? |
| |
| [Color Issues] |
| |
| Q-23: The X display I run x11vnc on is only 8 bits per pixel (bpp) |
| PseudoColor (i.e. only 256 distinct colors.) The x11vnc colors may |
| start out OK, but after a while they are incorrect in certain windows. |
| |
| Q-24: Color problems: Why are the colors for some windows incorrect in |
| x11vnc? BTW, my X display has nice overlay/multi-depth visuals of |
| different color depths: e.g. there are both depth 8 and 24 visuals |
| available at the same time. |
| |
| Q-25: I am on a high color system (depth >= 24) but I seem to have |
| colormap problems. They either flash or everything is very dark. |
| |
| Q-26: How do I figure out the window id to supply to the -id windowid |
| option? |
| |
| Q-27: Why don't menus or other transient windows come up when I am |
| using the -id windowid option to view a single application window? |
| |
| Q-28: My X display is depth 24 at 24bpp (instead of the normal depth |
| 24 at 32bpp.) I'm having lots of color and visual problems with x11vnc |
| and/or vncviewer. What's up? |
| |
| [Xterminals] |
| |
| Q-29: Can I use x11vnc to view and interact with an Xterminal (e.g. |
| NCD) that is not running UNIX and so x11vnc cannot be run on it |
| directly? |
| |
| Q-30: How do I get my X permissions (MIT-MAGIC-COOKIE file) correct |
| for a Unix/Linux machine acting as an Xterminal? |
| |
| [Sun Rays] |
| |
| Q-31: I'm having trouble using x11vnc with my Sun Ray session. |
| |
| [Remote Control] |
| |
| Q-32: How do I stop x11vnc once it is running in the background? |
| |
| Q-33: Can I change settings in x11vnc without having to restart it? |
| Can I remote control it? |
| |
| [Security and Permissions] |
| |
| Q-34: How do I create a VNC password for use with x11vnc? |
| |
| Q-35: Can I make it so -storepasswd doesn't show my password on the |
| screen? |
| |
| Q-36: Can I have two passwords for VNC viewers, one for full access |
| and the other for view-only access to the display? |
| |
| Q-37: Can I have as many full-access and view-only passwords as I |
| like? |
| |
| Q-38: Does x11vnc support Unix usernames and passwords? Can I further |
| limit the set of Unix usernames who can connect to the VNC desktop? |
| |
| Q-39: Can I supply an external program to provide my own custom login |
| method (e.g. Dynamic/One-time passwords or non-Unix (LDAP) usernames |
| and passwords)? |
| |
| Q-40: Why does x11vnc exit as soon as the VNC viewer disconnects? And |
| why doesn't it allow more than one VNC viewer to connect at the same |
| time? |
| |
| Q-41: Can I limit which machines incoming VNC clients can connect |
| from? |
| |
| Q-42: How do I build x11vnc/libvncserver with libwrap (tcp_wrappers) |
| support? |
| |
| Q-43: Can I have x11vnc only listen on one network interface (e.g. |
| internal LAN) rather than having it listen on all network interfaces |
| and relying on -allow to filter unwanted connections out? |
| |
| Q-44: Now that -localhost implies listening only on the loopback |
| interface, how I can occasionally allow in a non-localhost via the -R |
| allowonce remote control command? |
| |
| Q-45: Can I fine tune what types of user input are allowed? E.g. have |
| some users just be able to move the mouse, but not click or type |
| anything? |
| |
| Q-46: Can I prompt the user at the local X display whether the |
| incoming VNC client should be accepted or not? Can I decide to make |
| some clients view-only? How about running an arbitrary program to make |
| the decisions? |
| |
| Q-47: I start x11vnc as root because it is launched via inetd(8) or a |
| display manager like gdm(1). Can I have x11vnc later switch to a |
| different user? |
| |
| Q-48: I use a screen-lock when I leave my workstation (e.g. |
| xscreensaver or xlock.) When I remotely access my workstation desktop |
| via x11vnc I can unlock the desktop fine, but I am worried people will |
| see my activities on the physical monitor. What can I do to prevent |
| this, or at least make it more difficult? |
| |
| Q-49: Can I have x11vnc automatically lock the screen when I |
| disconnect the VNC viewer? |
| |
| [Encrypted Connections] |
| |
| Q-50: How can I tunnel my connection to x11vnc via an encrypted SSH |
| channel between two Unix machines? |
| |
| Q-51: How can I tunnel my connection to x11vnc via an encrypted SSH |
| channel from Windows using an SSH client like Putty? |
| |
| Q-52: How can I tunnel my connection to x11vnc via an encrypted SSL |
| channel using an external tool like stunnel? |
| |
| Q-53: Does x11vnc have built-in SSL tunneling? |
| |
| Q-54: How do I use VNC Viewers with built-in SSL tunneling? |
| |
| Q-55: How do I use the Java applet VNC Viewer with built-in SSL |
| tunneling when going through a Web Proxy? |
| |
| Q-56: Can Apache web server act as a gateway for users to connect via |
| SSL from the Internet with a Web browser to x11vnc running on their |
| workstations behind a firewall? |
| |
| Q-57: Can I create and use my own SSL Certificate Authority (CA) with |
| x11vnc? |
| |
| [Display Managers and Services] |
| |
| Q-58: How can I run x11vnc as a "service" that is always available? |
| |
| Q-59: How can I use x11vnc to connect to an X login screen like xdm, |
| GNOME gdm, KDE kdm, or CDE dtlogin? (i.e. nobody is logged into an X |
| session yet.) |
| |
| Q-60: Can I run x11vnc out of inetd(8)? How about xinetd(8)? |
| |
| Q-61: Can I have x11vnc advertise its VNC service and port via mDNS / |
| Zeroconf (e.g. Avahi) so VNC viewers on the local network can detect |
| it automatically? |
| |
| Q-62: Can I have x11vnc allow a user to log in with her UNIX username |
| and password and then have it find her X session display on that |
| machine and then attach to it? How about starting an X session if one |
| cannot be found? |
| |
| Q-63: Can I have x11vnc restart itself after it terminates? |
| |
| Q-64: How do I make x11vnc work with the Java VNC viewer applet in a |
| web browser? |
| |
| Q-65: Are reverse connections (i.e. the VNC server connecting to the |
| VNC viewer) using "vncviewer -listen" and vncconnect(1) supported? |
| |
| Q-66: Can reverse connections be made to go through a Web or SOCKS |
| proxy or SSH? |
| |
| Q-67: Can x11vnc provide a multi-user desktop web login service as an |
| Apache CGI or PHP script? |
| |
| Q-68: Can I use x11vnc as a replacement for Xvnc? (i.e. not for a real |
| display, but for a virtual one I keep around.) |
| |
| Q-69: How can I use x11vnc on "headless" machines? Why might I want |
| to? |
| |
| [Resource Usage and Performance] |
| |
| Q-70: I have lots of memory, but why does x11vnc fail with shmget: |
| No space left on device or Minor opcode of failed request: 1 |
| (X_ShmAttach)? |
| |
| Q-71: How can I make x11vnc use less system resources? |
| |
| Q-72: How can I make x11vnc use MORE system resources? |
| |
| Q-73: I use x11vnc over a slow link with high latency (e.g. dialup |
| modem or broadband), is there anything I can do to speed things up? |
| |
| Q-74: Does x11vnc support the X DAMAGE Xserver extension to find |
| modified regions of the screen quickly and efficiently? |
| |
| Q-75: My OpenGL application shows no screen updates unless I supply |
| the -noxdamage option to x11vnc. |
| |
| Q-76: When I drag windows around with the mouse or scroll up and down |
| things really bog down (unless I do the drag in a single, quick |
| motion.) Is there anything to do to improve things? |
| |
| Q-77: Why not do something like wireframe animations to avoid the |
| windows "lurching" when being moved or resized? |
| |
| Q-78: Can x11vnc try to apply heuristics to detect when a window is |
| scrolling its contents and use the CopyRect encoding for a speedup? |
| |
| Q-79: Can x11vnc do client-side caching of pixel data? I.e. so when |
| that pixel data is needed again it does not have to be retransmitted |
| over the network. |
| |
| Q-80: Does x11vnc support TurboVNC? |
| |
| [Mouse Cursor Shapes] |
| |
| Q-81: Why isn't the mouse cursor shape (the little icon shape where |
| the mouse pointer is) correct as I move from window to window? |
| |
| Q-82: When using XFIXES cursorshape mode, some of the cursors look |
| really bad with extra black borders around the cursor and other cruft. |
| How can I improve their appearance? |
| |
| Q-83: In XFIXES mode, are there any hacks to handle cursor |
| transparency ("alpha channel") exactly? |
| |
| [Mouse Pointer] |
| |
| Q-84: Why does the mouse arrow just stay in one corner in my |
| vncviewer, whereas my cursor (that does move) is just a dot? |
| |
| Q-85: Can I take advantage of the TightVNC extension to the VNC |
| protocol where Cursor Positions Updates are sent back to all connected |
| clients (i.e. passive viewers can see the mouse cursor being moved |
| around by another viewer)? |
| |
| Q-86: Is it possible to swap the mouse buttons (e.g. left-handed |
| operation), or arbitrarily remap them? How about mapping button clicks |
| to keystrokes, e.g. to partially emulate Mouse wheel scrolling? |
| |
| [Keyboard Issues] |
| |
| Q-87: How can I get my AltGr and Shift modifiers to work between |
| keyboards for different languages? |
| |
| Q-88: When I try to type a "<" (i.e. less than) instead I get ">" |
| (i.e. greater than)! Strangely, typing ">" works OK!! |
| |
| Q-89: Extra Character Inserted, E.g.: When I try to type a "<" (i.e. |
| less than) instead I get "<," (i.e. an extra comma.) |
| |
| Q-90: I'm using an "international" keyboard (e.g. German "de", or |
| Danish "dk") and the -modtweak mode works well if the VNC viewer is |
| run on a Unix/Linux machine with a similar keyboard. But if I run |
| the VNC viewer on Unix/Linux with a different keyboard (e.g. "us") or |
| Windows with any keyboard, I can't type some keys like: "@", "$", |
| "<", ">", etc. How can I fix this? |
| |
| Q-91: When typing I sometimes get double, triple, or more of my |
| keystrokes repeated. I'm sure I only typed them once, what can I do? |
| |
| Q-92: The x11vnc -norepeat mode is in effect, but I still get repeated |
| keystrokes!! |
| |
| Q-93: After using x11vnc for a while, I find that I cannot type some |
| (or any) characters or my mouse clicks and drags no longer have any |
| effect, or they lead to strange effects. What happened? |
| |
| Q-94: The machine where I run x11vnc has an AltGr key, but the local |
| machine where I run the VNC viewer does not. Is there a way I can map |
| a local unused key to send an AltGr? How about a Compose key as well? |
| |
| Q-95: I have a Sun machine I run x11vnc on. Its Sun keyboard has just |
| one Alt key labelled "Alt" and two Meta keys labelled with little |
| diamonds. The machine where I run the VNC viewer only has Alt keys. |
| How can I send a Meta keypress? (e.g. emacs needs this) |
| |
| Q-96: Running x11vnc on HP-UX I cannot type "#" I just get a "3" |
| instead. |
| |
| Q-97: Can I map a keystroke to a mouse button click on the remote |
| machine? |
| |
| Q-98: How can I get Caps_Lock to work between my VNC viewer and |
| x11vnc? |
| |
| [Screen Related Issues and Features] |
| |
| Q-99: The remote display is larger (in number of pixels) than the |
| local display I am running the vncviewer on. I don't like the |
| vncviewer scrollbars, what I can do? |
| |
| Q-100: Does x11vnc support server-side framebuffer scaling? (E.g. to |
| make the desktop smaller.) |
| |
| Q-101: Does x11vnc work with Xinerama? (i.e. multiple monitors joined |
| together to form one big, single screen.) |
| |
| Q-102: Can I use x11vnc on a multi-headed display that is not Xinerama |
| (i.e. separate screens :0.0, :0.1, ... for each monitor)? |
| |
| Q-103: Can x11vnc show only a portion of the display? (E.g. for a |
| special purpose application or a very large screen.) |
| |
| Q-104: Does x11vnc support the XRANDR (X Resize, Rotate and |
| Reflection) extension? Whenever I rotate or resize the screen x11vnc |
| just seems to crash. |
| |
| Q-105: Independent of any XRANDR, can I have x11vnc rotate and/or |
| reflect the screen that the VNC viewers see? (e.g. for a handheld |
| whose screen is rotated 90 degrees.) |
| |
| Q-106: Why is the view in my VNC viewer completely black? Or why is |
| everything flashing around randomly? |
| |
| Q-107: I use Linux Virtual Terminals (VT's) to implement 'Fast User |
| Switching' between users' sessions (e.g. Betty is on Ctrl-Alt-F7, |
| Bobby is on Ctrl-Alt-F8, and Sid is on Ctrl-Alt-F1: they use those |
| keystrokes to switch between their sessions.) How come the view in a |
| VNC viewer connecting to x11vnc is either completely black or |
| otherwise all messed up unless the X session x11vnc is attached to is |
| in the active VT? |
| |
| Q-108: I am using x11vnc where my local machine has "popup/hidden |
| taskbars" and the remote display where x11vnc runs also has |
| "popup/hidden taskbars" and they interfere and fight with each other. |
| What can I do? |
| |
| Q-109: Help! x11vnc and my KDE screensaver keep switching each other |
| on and off every few seconds. |
| |
| Q-110: I am running the compiz 3D window manager (or beryl, MythTv, |
| Google Earth, or some other OpenGL app) and I do not get screen |
| updates in x11vnc. |
| |
| Q-111: Can I use x11vnc to view my VMWare session remotely? |
| |
| [Exporting non-X11 devices via VNC] |
| |
| Q-112: Can non-X devices (e.g. a raw framebuffer) be viewed (and even |
| controlled) via VNC with x11vnc? |
| |
| Q-113: Can I export the Linux Console (Virtual Terminals) via VNC |
| using x11vnc? |
| |
| Q-114: Can I export via VNC a Webcam or TV tuner framebuffer using |
| x11vnc? |
| |
| Q-115: Can I connect via VNC to a Qt-embedded/Qt-enhanced/Qtopia |
| application running on my handheld, cell phone, or PC using the Linux |
| console framebuffer (i.e. not X11)? |
| |
| Q-116: How do I inject touch screen input into an |
| Qt-embedded/Qt-enhanced/Qtopia cell phone such as openmoko/qtmoko Neo |
| Freerunner? |
| |
| Q-117: Now that non-X11 devices can be exported via VNC using x11vnc, |
| can I build it with no dependencies on X11 header files and libraries? |
| |
| Q-118: How do I cross compile x11vnc for a different architecture than |
| my Linux i386 or amd64 PC? |
| |
| Q-119: Does x11vnc support Mac OS X Aqua/Quartz displays natively |
| (i.e. no X11 involved)? |
| |
| Q-120: Can x11vnc be used as a VNC reflector/repeater to improve |
| performance for the case of a large number of simultaneous VNC viewers |
| (e.g. classroom broadcasting or a large demo)? |
| |
| Q-121: Can x11vnc be used during a Linux, Solaris, etc. system |
| Installation so the Installation can be done remotely? |
| |
| [Misc: Clipboard, File Transfer/Sharing, Printing, Sound, Beeps, |
| Thanks, etc.] |
| |
| Q-122: Does the Clipboard/Selection get transferred between the |
| vncviewer and the X display? |
| |
| Q-123: Can I use x11vnc to record a Shock Wave Flash (or other format) |
| video of my desktop, e.g. to record a tutorial or demo? |
| |
| Q-124: Can I transfer files back and forth with x11vnc? |
| |
| Q-125: Which UltraVNC extensions are supported? |
| |
| Q-126: Can x11vnc emulate UltraVNC's Single Click helpdesk mode for |
| Unix? I.e. something very simple for a naive user to initiate a |
| reverse vnc connection from their Unix desktop to a helpdesk |
| operator's VNC Viewer. |
| |
| Q-127: Can I (temporarily) mount my local (viewer-side) Windows/Samba |
| File share on the machine where x11vnc is running? |
| |
| Q-128: Can I redirect CUPS print jobs from the remote desktop where |
| x11vnc is running to a printer on my local (viewer-side) machine? |
| |
| Q-129: How can I hear the sound (audio) from the remote applications |
| on the desktop I am viewing via x11vnc? |
| |
| Q-130: Why don't I hear the "Beeps" in my X session (e.g. when typing |
| tput bel in an xterm)? |
| |
| Q-131: Does x11vnc work with IPv6? |
| |
| Q-132: Thanks for your program or for your help! Can I make a |
| donation? |
| _________________________________________________________________ |
| |
| |
| [Building and Starting] |
| |
| Q-1: I can't get x11vnc to start up. It says "XOpenDisplay failed |
| (null)" or "Xlib: connection to ":0.0" refused by server Xlib: No |
| protocol specified" and then exits. What do I need to do? |
| |
| For the former error, you need to specify the X display to connect to |
| (it also needs to be on the same machine the x11vnc process is to run |
| on.) Set your DISPLAY environment variable (or use the -display |
| option) to specify it. Nearly always the correct value will be ":0" |
| (in fact, x11vnc will now assume :0 if given no other information.) |
| |
| |
| For the latter error, you need to set up the X11 permissions |
| correctly. |
| |
| To make sure X11 permissions are the problem do this simple test: |
| while sitting at the physical X display open a terminal window |
| (gnome-terminal, xterm, etc.) You should be able to run x11vnc |
| successfully without any need for special steps or command line |
| options in that terminal (i.e. just type "x11vnc".) If that works OK |
| then you know X11 permissions are the only thing preventing it from |
| working when you try to start x11vnc via, say, a remote shell. |
| |
| How to Solve: See the xauth(1), Xsecurity(7), and xhost(1) man pages |
| or this Howto for much info on X11 permissions. For example, you may |
| need to set your XAUTHORITY environment variable (or use the -auth |
| option) to point to the correct MIT-MAGIC-COOKIE file (e.g. |
| /home/joe/.Xauthority or /var/gdm/:0.Xauth or /var/lib/kdm/A:0-crWk72K |
| or /tmp/.gdmzndVlR, etc, etc.), or simply be sure you run x11vnc as |
| the correct user (i.e. the user who is logged into the X session you |
| wish to view.) |
| |
| Note: The MIT cookie file contains the secret key that allows x11vnc |
| to connect to the desired X display. |
| |
| If, say, sshd has set XAUTHORITY to point to a random file it has |
| created for X forwarding that will cause problems. (Under some |
| circumstances even su(1) and telnet(1) can set XAUTHORITY. See also |
| the gdm parameter NeverPlaceCookiesOnNFS that sets XAUTHORITY to a |
| random filename in /tmp for the whole X session.) |
| |
| Running x11vnc as root is often not enough: you need to know where the |
| MIT-MAGIC-COOKIE file for the desired X display is. |
| |
| Example solution: |
| x11vnc -display :0 -auth /var/gdm/:0.Xauth |
| |
| (this is for the display manager gdm and requires root permission to |
| read the gdm cookie file, see this faq for other display manager |
| cookie file names.) |
| |
| Note as of Feb/2007 you can also try the -find option instead of |
| "-display ..." and see if that finds your display and Xauthority. |
| |
| Less safe, but to avoid figuring out where the correct XAUTHORITY file |
| is, if the person sitting at the physical X session types "xhost |
| +localhost" then one should be able to attach x11vnc to the session |
| (from the same machine.) The person could then type "xhost -localhost" |
| after x11vnc has connected to go back to the default permissions. |
| Also, for some situations the "-users lurk=" option may soon be of use |
| (please read the documentation on the -users option.) |
| |
| To test out your X11 permissions from a remote shell, set DISPLAY and |
| possibly XAUTHORITY (see your shell's man page, bash(1), tcsh(1), on |
| how to set environment variables) and type xdpyinfo in the same place |
| you will be typing (or otherwise running) x11vnc. If information is |
| printed out about the X display (screen sizes, supported extensions, |
| color visuals info) that means the X11 permissions are set up |
| properly: xdpyinfo successfully connected to DISPLAY! You could also |
| type xclock and make sure no errors are reported (a clock should |
| appear on the X display, press Ctrl-C to stop it.) If these work, then |
| typing "x11vnc" in the same environment should also work. |
| |
| Important: if you cannot get your X11 permissions so that the xdpyinfo |
| or xclock tests work, x11vnc also will not work (all of these X |
| clients must be allowed to connect to the X server to function |
| properly.) |
| |
| Firewalls: Speaking of permissions, it should go without saying that |
| the host-level firewall will need to be configured to allow |
| connections in on a port. E.g. 5900 (default VNC port) or 22 (default |
| SSH port for tunnelling VNC.) Most systems these days have firewalls |
| turned on by default, so you will actively have to do something to |
| poke a hole in the firewall at the desired port number. See your |
| system administration tool for Firewall settings (Yast, Firestarter, |
| etc.) |
| |
| |
| Q-2: I can't get x11vnc and/or libvncserver to compile. |
| |
| Make sure you have gcc (or other C compiler) and all of the required |
| libraries and the corresponding -dev/-devel packages installed. These |
| include Xorg/XFree86, libX11, libjpeg, libz, libssl, ... and don't |
| forget the devs: libjpeg-dev, libssl-dev ... |
| |
| The most common build problem that people encounter is that the |
| necessary X11 libraries are installed on their system however it does |
| not have the corresponding -dev/-devel packages installed. These dev |
| packages include C header files and build-time .so symlink. It is a |
| shame the current trend in distros is to not install the dev package |
| by default when the the library runtime package is installed... (it |
| diminishes the power of open source) |
| |
| As of Nov/2006 here is a list of libraries that x11vnc usually likes |
| to use: |
| libc.so libX11.so libXtst.so libXext.so |
| libXfixes.so libXdamage.so libXinerama.so libXrandr.so |
| libz.so libjpeg.so libpthread.so |
| libssl.so libcrypto.so libcrypt.so |
| |
| although x11vnc will be pretty usable with the subset: libc.so, |
| libX11.so, libXtst.so, libXext.so, libz.so, and libjpeg.so. |
| |
| After running the libvncserver configure, carefully examine the output |
| and the messages in the config.log file looking for missing |
| components. For example, if the configure output looks like: |
| checking how to run the C preprocessor... gcc -E |
| checking for X... no |
| checking for XkbSelectEvents in -lX11... no |
| checking for XineramaQueryScreens in -lXinerama... no |
| checking for XTestFakeKeyEvent in -lXtst... no |
| |
| or even worse: |
| checking for C compiler default output file name... configure: error: |
| C compiler cannot create executables |
| See `config.log' for more details. |
| |
| there is quite a bit wrong with the build environment. Hopefully |
| simply adding -dev packages and/or gcc or make will fix it. |
| |
| For Debian the list seems to be: |
| gcc |
| make |
| libc6-dev |
| libjpeg8-dev (formerly libjpeg62-dev) |
| libx11-dev |
| x11proto-core-dev (formerly x-dev) |
| libxext-dev |
| libxtst-dev |
| libxdamage-dev |
| libxfixes-dev |
| libxrandr-dev |
| libxinerama-dev |
| libxss-dev (formerly xlibs-static-dev) |
| zlib1g-dev |
| libssl-dev |
| libavahi-client-dev |
| linux-libc-dev (only needed for linux console rawfb support) |
| |
| Note that depending on your OS version the above names may have been |
| changed and/or additional packages may be needed. |
| |
| For Redhat the list seems to be: |
| gcc |
| make |
| glibc-devel |
| libjpeg-devel |
| libX11-devel |
| xorg-x11-proto-devel |
| libXdamage-devel |
| libXfixes-devel |
| libXrandr-devel |
| zlib-devel |
| openssl-devel |
| avahi-devel |
| kernel-headers (only needed for linux console rawfb support) |
| |
| For other distros or OS's the package names may not be the same but |
| will look similar. Also, distros tend to rename packages as well so |
| the above list may be out of date. So only use the above lists as |
| hints for the package names that are needed. |
| |
| Have a look at Misc. Build Problems for additional fixes. |
| |
| Note: there is growing trend in Linux and other distros to slice up |
| core X11 software into more and smaller packages. So be prepared for |
| more headaches compiling software... |
| |
| |
| Q-3: I just built x11vnc successfully, but when I use it my keystrokes |
| and mouse button clicks are ignored (I am able to move the mouse |
| though.) |
| |
| This is most likely due to you not having a working build environment |
| for the XTEST client library libXtst.so. The library is probably |
| present on your system, but the package installing the build header |
| file is missing. |
| |
| If you were watching carefully while configure was running you would |
| have seen: |
| checking for XTestFakeKeyEvent in -lXtst... no |
| |
| The solution is to add the necessary build environment package (and |
| the library package if that is missing too.) On Debian the build |
| package is libxtst-dev. Other distros/OS's may have it in another |
| package. |
| |
| x11vnc will build without support for this library (e.g. perhaps one |
| wants a view-only x11vnc on a stripped down or embedded system...) And |
| at runtime it will also continue to run even if the X server it |
| connects to does not support XTEST. In both cases it cannot inject |
| keystrokes or button clicks since XTEST is needed for that (it can |
| still move the mouse pointer using the X API XWarpPointer().) |
| |
| You will see a warning message something like this at run time: |
| 20/03/2005 22:33:09 WARNING: XTEST extension not available (either missing fr |
| om |
| 20/03/2005 22:33:09 display or client library libXtst missing at build time |
| .) |
| 20/03/2005 22:33:09 MOST user input (pointer and keyboard) will be DISCARDE |
| D. |
| 20/03/2005 22:33:09 If display does have XTEST, be sure to build x11vnc wit |
| h |
| 20/03/2005 22:33:09 a working libXtst build environment (e.g. libxtst-dev, |
| 20/03/2005 22:33:09 or other packages.) |
| 20/03/2005 22:33:09 No XTEST extension, switching to -xwarppointer mode for |
| 20/03/2005 22:33:09 pointer motion input. |
| |
| Also, as of Nov/2006 there will be a configure build time warning as |
| well: |
| ... |
| checking for XFixesGetCursorImage in -lXfixes... yes |
| checking for XDamageQueryExtension in -lXdamage... yes |
| configure: WARNING: |
| ========================================================================== |
| A working build environment for the XTEST extension was not found (libXtst). |
| An x11vnc built this way will be only barely usable. You will be able to |
| move the mouse but not click or type. There can also be deadlocks if an |
| application grabs the X server. |
| |
| It is recommended that you install the necessary development packages |
| for XTEST (perhaps it is named something like libxtst-dev) and run |
| configure again. |
| ========================================================================== |
| |
| |
| Q-4: Help, I need to run x11vnc on Solaris 2.5.1 (or other old |
| Unix/Linux) and it doesn't compile! |
| |
| We apologize that x11vnc does not build cleanly on older versions of |
| Solaris, Linux, etc.: very few users are on these old releases. |
| |
| We have heard that since Dec/2004 a Solaris 2.6 built x11vnc will run |
| on Solaris Solaris 2.5 and 2.5.1 (since a workaround for XConvertCase |
| is provided.) |
| |
| In any event, here is a workaround for Solaris 2.5.1 (and perhaps |
| earlier and perhaps non-Solaris): |
| |
| First use the environment settings (CPPFLAGS, LDFLAGS, etc.) in the |
| above Solaris build script to run the configure command. That should |
| succeed without failure. Then you have to hand edit the autogenerated |
| rfb/rfbconfig.h file in the source tree, and just before the last |
| #endif at the bottom of that file insert these workaround lines: |
| struct timeval _tmp_usleep_tv; |
| #define usleep(x) \ |
| _tmp_usleep_tv.tv_sec = (x) / 1000000; \ |
| _tmp_usleep_tv.tv_usec = (x) % 1000000; \ |
| select(0, NULL, NULL, NULL, &_tmp_usleep_tv); |
| int gethostname(char *name, int namelen); |
| long random(); |
| int srandom(unsigned int seed); |
| #undef LIBVNCSERVER_HAVE_LIBPTHREAD |
| #define SHUT_RDWR 2 |
| typedef unsigned int in_addr_t; |
| #define snprintf(a, n, args...) sprintf((a), ## args) |
| |
| Then run make with the Solaris build script environment, everything |
| should compile without problems, and the resulting x11vnc binary |
| should work OK. If some non-x11vnc related programs fail (e.g. test |
| programs) and the x11vnc binary is not created try "make -k" to have |
| it keep going. Similar sorts of kludges in rfb/rfbconfig.h can be done |
| on other older OS (Solaris, Linux, ...) releases. |
| |
| Here are some notes for similar steps that need to be done to build on |
| SunOS 4.x |
| |
| Please let us know if you had to use the above workaround (and whether |
| it worked or not.) If there is enough demand we will try to push clean |
| compilations back to earlier Solaris, Linux, etc, releases. |
| |
| |
| Q-5: Where can I get a precompiled x11vnc binary for my Operating |
| System? |
| |
| Hopefully the build steps above and FAQ provide enough info for a |
| painless compile for most environments. Please report problems with |
| the x11vnc configure, make, etc. on your system (if your system is |
| known to compile other GNU packages successfully.) |
| |
| There are precompiled x11vnc binaries built by other groups that are |
| available at the following locations: |
| Slackware: (.tgz) http://www.linuxpackages.net/ |
| |
| SuSE: (.rpm) http:/software.opensuse.org/ Gentoo: (info) |
| http://gentoo-wiki.com/ and http://gentoo-portage.com/ FreeBSD: (.tbz) |
| http://www.freebsd.org/ http://www.freshports.org/net/x11vnc NetBSD: |
| (src) http://pkgsrc.se/x11/x11vnc OpenBSD: (.tgz) http://openports.se/ |
| Arch Linux: (.tgz) http://www.archlinux.org/ Nokia 770 (.deb) |
| http://mike.saunby.googlepages.com/x11vncfornokia7702 Sharp Zaurus |
| http://www.focv.com/ Debian: (.deb) http://packages.debian.org/x11vnc |
| Redhat/Fedora: (.rpm) http://packages.sw.be/x11vnc RPMforge |
| http://dag.wieers.com/rpm/packages/x11vnc/ (N.B.: unmaintained after |
| 0.9.3) Solaris: (pkg) http://www.sunfreeware.com/ |
| |
| If the above binaries don't work and building x11vnc on your OS fails |
| (and all else fails!) you can try one of My Collection of x11vnc |
| Binaries for various OS's and x11vnc releases. |
| |
| As a general note, the x11vnc program is simple enough you don't |
| really need to install a package: the binary will in most cases work |
| as is and from any location (as long as your system libraries are not |
| too old, etc.) So, for Linux distributions that are not one of the |
| above, the x11vnc binary from the above packages has a good chance of |
| working. You can "install" it by just copying the x11vnc binary to the |
| desired directory in your PATH. Tip on extracting files from a Debian |
| package: extract the archive via a command like: "ar x |
| x11vnc_0.6-2_i386.deb" and then you can find the binary in the |
| resulting data.tar.gz tar file. Also, rpm2cpio(1) is useful in |
| extracting files from rpm packages. |
| |
| If you use a standalone binary like this and also want x11vnc to serve |
| up the Java VNC Viewer jar file (either SSL enabled or regular one), |
| then you will need to extract the classes subdirectory from the source |
| tarball and point x11vnc to it via the -httpdir option. E.g.: |
| x11vnc -httpdir /path/to/x11vnc-0.9.9/classes/ssl ... |
| |
| |
| Q-6: Where can I get a VNC Viewer binary (or source code) for the |
| Operating System I will be viewing from? |
| |
| To obtain VNC viewers for the viewing side (Windows, Mac OS, or Unix) |
| try here: |
| * http://www.tightvnc.com/download.html |
| * http://www.realvnc.com/download-free.html |
| * http://sourceforge.net/projects/cotvnc/ |
| * http://www.ultravnc.com/ |
| * Our Enhanced TightVNC Viewer (SSVNC) |
| |
| [ssvnc.gif] |
| |
| |
| Q-7: How can I see all of x11vnc's command line options and |
| documentation on how to use them? |
| |
| Run: x11vnc -opts to list just the option names or run: x11vnc |
| -help for long descriptions about each option. The output is listed |
| here as well. Yes, x11vnc does have a lot of options, doesn't it... |
| |
| |
| Q-8: I don't like typing arcane command line options every time I |
| start x11vnc. What can I do? Is there a config file? Or a GUI? |
| |
| You could create a shell script that calls x11vnc with your options: |
| #!/bin/sh |
| # |
| # filename: X11vnc (i.e. not "x11vnc") |
| # It resides in a directory in $PATH. "chmod 755 X11vnc" has been run on it. |
| # |
| x11vnc -wait 50 -localhost -rfbauth $HOME/.vnc/passwd -display :0 $* |
| |
| a similar thing can be done via aliases in your shell (bash, tcsh, |
| csh, etc..) |
| |
| Or as of Jun/2004 you can use the simple $HOME/.x11vncrc config file |
| support. If that file exists, each line is taken as a command line |
| option. E.g. the above would be: |
| # this is a comment in my ~/.x11vncrc file |
| wait 50 # this is a comment to the end of the line. |
| -localhost # note: the leading "-" is optional. |
| rfbauth /home/fred/.vnc/passwd |
| display :0 |
| |
| As of Dec/2004 there is now a simple Tcl/Tk GUI based on the |
| remote-control functionality ("-R") that was added. The /usr/bin/wish |
| program is needed for operation. The gui is not particularly |
| user-friendly, it just provides a point and click mode to set all the |
| many x11vnc parameters and obtain help on them. It is also very useful |
| for testing. See the -gui option for more info. Examples: "x11vnc ... |
| -gui" and "x11vnc ... -gui other:0" in the latter case the gui is |
| displayed on other:0, not the X display x11vnc is polling. There is |
| also a "-gui tray" system tray mode. |
| |
| [tkx11vnc.gif] |
| |
| NOTE: You may need to install the "wish" or "tk" or "tk8.4" package |
| for the gui mode to work (the package name depends on your OS/distro.) |
| The tcl/tk "wish" interpreter is used. In debian (and so ubuntu too) |
| one would run "apt-get install tk" or perhaps "apt-get install tk8.4" |
| |
| |
| Q-9: How can I get the GUI to run in the System Tray, or at least be a |
| smaller, simpler icon? |
| |
| As of Jul/2005 the gui can run in a more friendly small icon mode |
| "-gui icon" or in the system tray: "-gui tray". It has balloon status, |
| a simple menu, and a Properities dialog. The full, complicated, gui is |
| only available under "Advanced". Other improvements were added as |
| well. Try "Misc -> simple_gui" for a gui with fewer esoteric menu |
| items. |
| |
| If the gui fails to embed itself in the system tray, do a retry via |
| "Window View -> icon" followed by "Window View -> tray" with the popup |
| menu. |
| |
| For inexperienced users starting up x11vnc and the GUI while sitting |
| at the physical X display (not remotely), using something like "x11vnc |
| -display :0 -gui tray=setpass" might be something for them that they |
| are accustomed to in a Desktop environment (it prompts for an initial |
| password, etc.) This is a basic "Share My Desktop" usage mode. |
| |
| As of Nov/2008 in x11vnc 0.9.6 there is a desktop menu item |
| (x11vnc.desktop) that runs this command: |
| x11vnc -gui tray=setpass -rfbport PROMPT -logfile %HOME/.x11vnc.log.%VNCDISP |
| LAY |
| |
| which also prompts for which VNC port to use and a couple other |
| parameters. |
| |
| |
| Q-10: How can I get x11vnc to listen on a different port besides the |
| default VNC port (5900)? |
| |
| Use something like, e.g., "x11vnc -rfbport 5901" to force it to use |
| port 5901 (this is VNC display :1.) If something else is using that |
| port x11vnc will exit immediately. If you do not supply the -rfbport |
| option, it will autoprobe starting at 5900 and work its way up to 5999 |
| looking for a free port to listen on. In that case, watch for the |
| PORT=59xx line to see which port it found, then subtract 5900 from it |
| for the VNC display number to enter into the VNC Viewer(s). |
| |
| The "-N" option will try to match the VNC display number to the X |
| display (e.g. X11 DISPLAY of :5 (port 6005) will have VNC display :5 |
| (port 5905).) |
| |
| Also see the "-autoport n" option to indicated at which value the auto |
| probing should start at. |
| |
| |
| Q-11: My Firewall/Router doesn't allow VNC Viewers to connect to |
| x11vnc. |
| |
| See the Firewalls/Routers discussion. |
| |
| |
| Q-12: Is it possible for a VNC Viewer and a VNC Server to connect to |
| each other even though both are behind Firewalls that block all |
| incoming connections? |
| |
| This is very difficult or impossible to do unless a third machine, |
| reachable by both, is used as a relay. So we assume a third machine is |
| somehow being used as a relay. |
| |
| (Update: It may be possible to do "NAT-2-NAT" without a relay machine |
| by using a UDP tunnel such as http://samy.pl/pwnat/. All that is |
| required is that both NAT firewalls allow in UDP packets from an IP |
| address to which a UDP packet has recently been sent to. If you try it |
| out let us know how it went.) |
| |
| In the following discussion, we will suppose port 5950 is being used |
| on the relay machine as the VNC port for the rendezvous. |
| |
| A way to rendezvous is to have the VNC Server start a reverse |
| connection to the relay machine: |
| x11vnc -connect third-machine.net:5950 ... |
| |
| and the VNC viewer forward connects as usual: |
| vncviewer third-machine.net:50 |
| |
| Or maybe two ports would be involved, e.g. the viewer goes to display |
| :51 (5951.) It depends on the relay software being used. |
| |
| What software to run on third-machine? A TCP relay of some sort could |
| be used... Try a google search on "tcp relay" or "ip relay". However, |
| note that this isn't a simple redirection because it hooks up two |
| incoming connections. You can look at our UltraVNC repeater |
| implementation ultravnc_repeater.pl for ideas and possibly to |
| customize. |
| |
| Also, if you are not the admin of third-machine you'd have to convince |
| the owner to allow you to install this software (and he would likely |
| need to open his server's firewall to allow the port through.) |
| |
| It is recommended that SSL is used for encryption (e.g. "-ssl SAVE") |
| when going over the internet. |
| |
| We have a prototype for performing a rendezvous via a Web Server |
| acting as the relay machine. Download the vncxfer CGI script and see |
| the instructions at the top. |
| |
| Once that CGI script is set up on the website, both users go to, say, |
| http://somesite.com/vncxfer (or maybe a "/cgi-bin" directory or ".cgi" |
| suffix must be used.) Previously, both have agreed on the same session |
| name (say by phone or email) , e.g. "5cows", and put that into the |
| entry form on the vncxfer starting page (hopefully separated by a few |
| seconds, so the relay helper can fully start up at the first request.) |
| |
| The page returned tells them the hostname and port number and possible |
| command to use for forward (VNC Viewer) and reverse (VNC Server, i.e. |
| x11vnc) connections as described above. |
| |
| Also since Oct/2007, x11vnc can connect directly (no web browser), |
| like this: |
| x11vnc ... -connect localhost:0 -proxy 'http://somesite.com/vncxfer?session= |
| 5cows&' |
| |
| Unfortunately the prototype requires that the Web server's firewall |
| allow in the port (e.g. 5950) used for the rendezvous. Most web |
| servers are not configured to do this, so you would need to ask the |
| admin to do this for you. Nearly all free webspace sites, e.g. |
| www.zendurl.com, will not allow your CGI script to be an open relay |
| like this. (If you find one that does allow this, let me know!) |
| |
| Maybe someday a clever trick will be thought up to relax the listening |
| port requirement (e.g. use HTTP/CGI itself for the transfer... it is |
| difficult to emulate a full-duplex TCP connection with them.) |
| |
| See also the Firewalls/Routers discussion and Reverse Connection Proxy |
| discussion. |
| |
| |
| SSH method: If both users (i.e. one on Viewer-side and the other on |
| x11vnc server side) have SSH access to a common machine on the |
| internet (or otherwise mutually reachable), then SSH plumbing can be |
| used to solve this problem. The users create SSH tunnels going through |
| the SSH login machine. |
| |
| Instead of assuming port 5900 is free on the SSH machine, we will |
| assume both users agreed to use 5933. This will illustrate how to use |
| a different port for the redir. It could be any port, what matters is |
| that both parties refer to the same one. |
| |
| Set up the Tunnel from the VNC Server side: |
| ssh -t -R 5933:localhost:5900 user@third-machine.net |
| |
| Set up the Tunnel from the VNC Viewer side: |
| ssh -t -L 5900:localhost:5933 user@third-machine.net |
| |
| Run Server on the VNC Server side: |
| x11vnc -rfbport 5900 -localhost ... |
| |
| Run Viewer on the VNC Viewer side: |
| vncviewer -encodings "copyrect tight zrle hextile" localhost:0 |
| |
| (we assume the old-style -encodings option needs to be used. See here |
| for details.) |
| |
| If the SSH machine has been configured (see sshd_config(5)) with the |
| option GatewayPorts=yes, then the tunnel set up by the VNC Server will |
| be reachable directly by the VNC viewer (as long as the SSH machine's |
| firewall does not block the port, 5933 in this example.) So in that |
| case the Viewer side does not need to run any ssh command, but rather |
| only runs: |
| vncviewer third-machine.net:33 |
| |
| In this case we recommend SSL be used for encryption. |
| |
| The creation of both tunnels can be automated. As of Oct/2007 the -ssh |
| x11vnc option is available and so only this command needs to be run on |
| the VNC Server side: |
| x11vnc -ssh user@third-machine.net:33 ... |
| |
| (the SSH passphrase may need to be supplied.) |
| |
| To automate on the VNC Viewer side, the user can use the Enhanced |
| TightVNC Viewer (SSVNC) by: |
| * Clicking on 'Use SSH' |
| * Entering user@third-machine.net:33 into 'VNC Host:Display' entry |
| box |
| * Clicking on 'Connect' |
| |
| As above, if the SSH GatewayPorts=yes setting is configured the Viewer |
| side doesn't need to create a SSH tunnel. In SSVNC the Viewer user |
| could instead select 'Use SSL' and then, e.g., on the Server side |
| supply "-ssl SAVE" to x11vnc. Then end-to-end SSL encryption would be |
| used (in addition to the SSH encryption on the Server-side leg.) |
| |
| |
| Q-13: Can I make x11vnc more quiet and also go into the background |
| after starting up? |
| |
| Use the -q and -bg options, respectively. (also: -quiet is an alias |
| for -q) |
| |
| Note that under -bg the stderr messages will be lost unless you use |
| the "-o logfile" option. |
| |
| |
| Q-14: Sometimes when a VNC viewer dies abruptly, x11vnc also dies with |
| the error message like: "Broken pipe". I'm using the -forever mode and |
| I want x11vnc to keep running. |
| |
| As of Jan/2004 the SIGPIPE signal is ignored. So if a viewer client |
| terminates abruptly, libvncserver will notice on the next I/O |
| operation and will close the connection and continue on. |
| |
| Up until of Apr/2004 the above fix only works for BSD signal systems |
| (Linux, FreeBSD, ...) For SYSV systems there is a workaround in place |
| since about Jun/2004. |
| |
| |
| Q-15: The Windows TightVNC 1.3.9 Viewer cannot connect to x11vnc. |
| |
| This appears to be fixed in x11vnc version 0.9 and later. If you need |
| to use an earlier version of x11vnc, try using the "-rfbversion 3.7" |
| option. In general sometimes one can get a misbehaving viewer to work |
| by supplying rfb versions 3.7 or 3.3. |
| |
| |
| Q-16: KDE's krdc VNC viewer cannot connect to x11vnc. |
| |
| This has been fixed in x11vnc version 0.8.4. More info here, here, and |
| here. |
| |
| |
| Q-17: When I start x11vnc on an Alpha Tru64 workstation the X server |
| crashes! |
| |
| This is a bug in the X server obviously; an X client should never be |
| able to crash it. |
| |
| The problem seems to be with the RECORD X extension and so a |
| workaround is to use the "-noxrecord" x11vnc command line option. |
| |
| |
| Q-18: When running x11vnc on an IBM AIX workstation after a few |
| minutes the VNC connection freezes. |
| |
| One user reports when running x11vnc on AIX 5.3 in his CDE session |
| after a few minutes or seconds x11vnc will "freeze" (no more updates |
| being sent, etc.) The freezing appeared to be worse for versions later |
| than 0.9.2. |
| |
| The problem seems to be with the RECORD X extension on AIX and so a |
| workaround is to use the "-noxrecord" x11vnc command line option. The |
| user found no freezes occurred when using that option. |
| |
| |
| Q-19: Are there any build-time customizations possible, e.g. change |
| defaults, create a smaller binary, etc? |
| |
| There are some options. They are enabled by adding something like |
| -Dxxxx=1 to the CPPFLAGS environment variable before running configure |
| (see the build notes for general background.) |
| /* |
| * Mar/2006 |
| * Build-time customization via CPPFLAGS. |
| * |
| * Summary of options to include in CPPFLAGS for custom builds: |
| * |
| * -DVNCSHARED to have the vnc display shared by default. |
| * -DFOREVER to have -forever on by default. |
| * -DNOREPEAT=0 to have -repeat on by default. |
| * -DADDKEYSYMS=0 to have -noadd_keysyms the default. |
| * |
| * -DREMOTE_DEFAULT=0 to disable remote-control on by default (-yesremote.) |
| * -DREMOTE_CONTROL=0 to disable remote-control mechanism completely. |
| * -DEXTERNAL_COMMANDS=0 to disable the running of all external commands. |
| * -DFILEXFER=0 disable filexfer. |
| * |
| * -DHARDWIRE_PASSWD=... hardwired passwords, quoting necessary. |
| * -DHARDWIRE_VIEWPASSWD=... |
| * -DNOPW=1 make -nopw the default (skip warning) |
| * -DUSEPW=1 make -usepw the default |
| * -DPASSWD_REQUIRED=1 exit unless a password is supplied. |
| * -DPASSWD_UNLESS_NOPW=1 exit unless a password is supplied and no -nopw. |
| * |
| * -DWIREFRAME=0 to have -nowireframe as the default. |
| * -DWIREFRAME_COPYRECT=0 to have -nowirecopyrect as the default. |
| * -DWIREFRAME_PARMS=... set default -wirecopyrect parameters. |
| * -DSCROLL_COPYRECT=0 to have -noscrollcopyrect as the default. |
| * -DSCROLL_COPYRECT_PARMS=... set default -scrollcopyrect parameters. |
| * -DSCALING_COPYRECT=0 |
| * -DXDAMAGE=0 to have -noxdamage as the default. |
| * -DSKIPDUPS=0 to have -noskip_dups as the default or vice versa. |
| * |
| * -DPOINTER_MODE_DEFAULT={0,1,2,3,4} set default -pointer_mode. |
| * -DBOLDLY_CLOSE_DISPLAY=0 to not close X DISPLAY under -rawfb. |
| * -DSMALL_FOOTPRINT=1 for smaller binary size (no help, no gui, etc) |
| * use 2 or 3 for even smaller footprint. |
| * -DNOGUI do not include the gui tkx11vnc. |
| * -DPOLL_8TO24_DELAY=N |
| * -DDEBUG_XEVENTS=1 enable printout for X events. |
| * |
| * Set these in CPPFLAGS before running configure. E.g.: |
| * |
| * % env CPPFLAGS="-DFOREVER -DREMOTE_CONTROL=0" ./configure |
| * % make |
| */ |
| |
| If other things (e.g. "-I ...") are needed in CPPFLAGS add them as |
| well. |
| |
| On some systems is seems you need to set LC_ALL=C for configure to |
| work properly... |
| |
| Be careful the following two variables: HARDWIRE_PASSWD and |
| HARDWIRE_VIEWPASSWD. If set (remember to include the double quotes |
| around the string), they will be used as default values for the |
| -passwd and -viewpasswd options. Of course the strings will exist |
| unobscured in the x11vnc binary: it better not be readable by |
| unintendeds. Perhaps this is of use in remote access for an embedded |
| application, etc... |
| |
| Let us know if more build-time customizations would be useful. |
| |
| |
| [Win2VNC Related] |
| |
| Q-20: I have two separate machine displays in front of me, one Windows |
| the other X11: can I use x11vnc in combination with Win2VNC in |
| dual-screen mode to pass the keystrokes and mouse motions to the X11 |
| display? |
| |
| Yes, for best response start up x11vnc with the "-nofb" option |
| (disables framebuffer polling, and does other optimizations) on the |
| secondary display (X11) machine. Then start up Win2VNC on the primary |
| display (Windows) referring it to the secondary display. |
| |
| This will also work X11 to X11 using x2vnc, however you would probably |
| just want to avoid VNC and use x2x for that. |
| |
| For reference, here are some links to Win2VNC-like programs for |
| multiple monitor setups: |
| * Original Win2VNC |
| * Enhanced Win2VNC (broken?) and sourceforge link |
| * x2vnc |
| * x2x |
| * zvnc (MorphOS) |
| |
| All of them will work with x11vnc (except x2x where it is not needed.) |
| |
| |
| Q-21: I am running Win2VNC on my Windows machine and "x11vnc -nofb" on |
| Unix to pass keyboard and mouse to the Unix monitor. Whenever I start |
| Win2VNC it quickly disconnects and x11vnc says: |
| rfbProcessClientNormalMessage: read: Connection reset by peer |
| |
| Is the default visual of the X display you run x11vnc on low color |
| (e.g. 8 bit per pixel PseudoColor)? (you can run xdpyinfo to check, |
| look in the "screen" section.) There seems to be a bug in Win2VNC in |
| that it cannot deal correctly with colormaps (PseudoColor is the most |
| common example of a visual with a colormap.) |
| |
| If so, there are a couple options. 1) Can you set the default visual |
| on your display to be depth 24 TrueColor? Sun machines often have 8+24 |
| overlay/multi-depth visuals, and you can make the default visual depth |
| 24 TrueColor (see fbconfig(1) and Xsun(1).) 2) As of Feb/2004 x11vnc |
| has the -visual option to allow you to force the framebuffer visual to |
| whatever you want (this usually messes up the colors unless you are |
| very clever.) In this case, the option provides a convenient |
| workaround for the Win2VNC bug: |
| x11vnc -nofb -visual TrueColor -display :0 ... |
| |
| So the visual will be set to 8bpp TrueColor and Win2VNC can handle |
| this. Since Win2VNC does not use the framebuffer data there should be |
| no problems in doing this. |
| |
| Q-22: Can I run "x11vnc -nofb" on a Mac OS X machine to redirect mouse |
| and keyboard input to it from Windows and X11 machines via Win2VNC and |
| x2vnc, respectively? |
| |
| Yes, as of Nov/2006 you can. There may be a trick or two you'll need |
| to do to get the Clipboard exchange between the machines to work. |
| |
| |
| |
| [Color Issues] |
| |
| Q-23: The X display I run x11vnc on is only 8 bits per pixel (bpp) |
| PseudoColor (i.e. only 256 distinct colors.) The x11vnc colors may |
| start out OK, but after a while they are incorrect in certain windows. |
| |
| Use the -flashcmap option to have x11vnc watch for changes in the |
| colormap, and propagate those changes back to connected clients. This |
| can be slow (since the whole screen must be updated over the network |
| whenever the colormap changes.) This flashing colormap behavior often |
| happens if an application installs its own private colormap when the |
| mouse is in its window. "netscape -install" is a well-known historical |
| example of this. Consider reconfiguring the system to 16 bpp or depth |
| 24 TrueColor if at all possible. |
| |
| Also note the option -8to24 (Jan/2006) can often remove the need for |
| flashing the colormap. Everything is dynamically transformed to depth |
| 24 at 32 bpp using the colormaps. There may be painting errors however |
| (see the following FAQ for tips on reducing and correcting them.) |
| |
| In some rare cases (SCO unixware) the -notruecolor option has |
| corrected colors on 8bpp displays. The red, green, and blue masks were |
| non-zero in 8bpp PseudoColor on an obscure setup, and this option |
| corrected the problems. |
| |
| |
| Q-24: Color problems: Why are the colors for some windows incorrect in |
| x11vnc? BTW, my X display has nice overlay/multi-depth visuals of |
| different color depths: e.g. there are both depth 8 and 24 visuals |
| available at the same time. |
| |
| You may want to review the previous question regarding 8 bpp |
| PseudoColor. |
| |
| On some hardware (Sun/SPARC and SGI), the -overlay option discussed a |
| couple paragraphs down may solve this for you (you may want to skip to |
| it directly.) On other hardware the less robust -8to24 option may help |
| (also discussed below.) |
| |
| Run xdpyinfo(1) to see what the default visual is and what the depths |
| of the other visuals are. Does the default visual have a depth of 8 |
| but there are other visuals of depth 24? If it does, can you possibly |
| re-configure your X server to make a depth 24 visual the default? If |
| you can do it, this will save you a lot of grief WRT colors and x11vnc |
| (and for general usage too!) Here is how I do this on an old |
| Sparcstation 20 running Solaris 9 with SX graphics |
| xinit -- -dev /dev/fb defclass TrueColor defdepth 24 |
| |
| and it works nicely (note: to log into console from the dtlogin |
| window, select "Options -> Command Line Login", then login and enter |
| the above command.) See the -dev section of the Xsun(1) manpage for a |
| description of the above arguments. If you have root permission, a |
| more permanent and convenient thing to do is to record the arguments |
| in a line like: |
| :0 Local local_uid@console root /usr/openwin/bin/Xsun -dev /dev/fb defclass |
| TrueColor defdepth 24 |
| |
| in /etc/dt/config/Xservers (copy /usr/dt/config/Xservers.) Also look |
| at the fbconfig(1) and related manpages (e.g. ffbconfig, m64config, |
| pgxconfig, SUNWjfb_config, etc ...) for hardware framebuffer settings |
| that may achieve the same effect. |
| |
| In general for non-Sun machines, look at the "-cc class" and related |
| options in your X server manpage (perhaps Xserver(1)), it may allow |
| modifying the default visual (e.g. "-cc 4", see <X11/X.h> for the |
| visual class numbers.) On XFree86 some video card drivers (e.g. Matrox |
| mga) have settings like Option "Overlay" "24,8" to support multi-depth |
| overlays. For these, use the "-cc 4" X server command line option to |
| get a depth 24 default visual. |
| |
| |
| The -overlay mode: Another option is if the system with overlay |
| visuals is a Sun system running Solaris or SGI running IRIX you can |
| use the -overlay x11vnc option (Aug/2004) to have x11vnc use the |
| Solaris XReadScreen(3X11) function to poll the "true view" of the |
| whole screen at depth 24 TrueColor. XReadDisplay(3X11) is used on |
| IRIX. This is useful for Legacy applications (older versions of |
| Cadence CAD apps are mentioned by x11vnc users) that require the |
| default depth be 8bpp, or the app will use a 8bpp visual even if depth |
| 24 visuals are available, and so the default depth workaround |
| described in the previous paragraph is not sufficient for these apps. |
| |
| It seems that Xorg is working toward supporting XReadDisplay(3X11) as |
| part of the RENDER extension work. When it does support it and |
| provides a library API x11vnc will be modified to take advantage of |
| the feature to support -overlay on Linux, *BSD, etc. Until then see |
| the -8to24 mode below. |
| |
| Misc. notes on -overlay mode: An amusing by-product of -overlay mode |
| is that the mouse cursor shape is correct! (i.e. XFIXES is not |
| needed.) The -overlay mode may be somewhat slower than normal mode due |
| to the extra framebuffer manipulations that must be performed. Also, |
| on Solaris there is a bug in that for some popup menus, the windows |
| they overlap will have painting errors (flashing colors) while the |
| popup is up (a workaround is to disable SaveUnders by passing -su to |
| Xsun, e.g. in your /etc/dt/config/Xservers file.) |
| |
| |
| The -8to24 mode: The -8to24 x11vnc option (Jan/2006) is a kludge to |
| try to dynamically rewrite the pixel values so that the 8bpp part of |
| the screen is mapped onto depth 24 TrueColor. This is less robust than |
| the -overlay mode because it is done by x11vnc outside of the X |
| server. So only use it on OS's that do not support -overlay. The |
| -8to24 mode will work if the default visual is depth 24 or depth 8. It |
| scans for any windows within 3 levels of the root window that are 8bpp |
| (i.e. legacy application), or in general ones that are not using the |
| default visual. For the windows it finds it uses XGetSubImage() to |
| retrieve the pixels values and uses the correct indexed colormap to |
| create a depth 24 TrueColor view of the whole screen. This depth 24, |
| 32bpp view is exported via VNC. |
| |
| Even on pure 8bpp displays it can be used as an alternative to |
| -flashcmap to avoid color flashing completely. |
| |
| This scheme is approximate and can often lead to painting errors. You |
| can manually correct most painting errors by pressing 3 Alt_L's in a |
| row, or by using something like: -fixscreen V=3.0 to automatically |
| refresh the screen every 3 seconds. Also -fixscreen 8=3.0 has been |
| added to just refresh the non-default visual parts of the screen. |
| |
| In general the scheme uses many resources and may give rise to |
| sluggish behavior. If multiple windows are using different 8bpp |
| indexed colormaps all but one window may need to be iconified for the |
| colors to be correct. There are a number of tunable parameters to try |
| to adjust performance and painting accuracy. The option -8to24 |
| nogetimage can give a nice speedup if the default depth 24 X server |
| supports hiding the 8bpp bits in bits 25-32 of the framebuffer data. |
| On very slow machines -8to24 poll=0.2,cachewin=5.0 gives an useful |
| speedup. See the -8to24 help description for information on tunable |
| parameters, etc. |
| |
| |
| Colors still not working correctly? Run xwininfo on the application |
| with the incorrect colors to verify that the depth of its visual is |
| different from the default visual depth (gotten from xdpyinfo.) One |
| possible workaround in this case is to use the -id option to point |
| x11vnc at the application window itself. If the application is |
| complicated (lots of toplevel windows and popup menus) this may not be |
| acceptable, and may even crash x11vnc (but not the application.) See |
| also -appshare. |
| |
| It is theoretically possible to solve this problem in general (see |
| xwd(1) for example), but it does not seem trivial or sufficiently fast |
| for x11vnc to be able to do so in real time. The -8to24 method does |
| this approximately and is somewhat usable. Fortunately the -overlay |
| option works for Solaris machines with overlay visuals where most of |
| this problem occurs. |
| |
| |
| Q-25: I am on a high color system (depth >= 24) but I seem to have |
| colormap problems. They either flash or everything is very dark. |
| |
| This can happen if the default Visual (use xdpyinfo to list them) is |
| DirectColor instead of TrueColor. These are both usually used in high |
| color modes, but whereas TrueColor uses static ramps for the Red, |
| Green, and Blue components, DirectColor has arbitrary colormaps for |
| the Red, Green, and Blue Components. Currently x11vnc cannot decode |
| these colormaps and treats them just like TrueColor. |
| |
| The only workaround so far is to restart the X server with the "-cc 4" |
| option to force TrueColor as the default visual (DirectColor is "-cc |
| 5"; see /usr/include/X11/X.h.) The only place we have seen this is |
| with the virtual framebuffer server Xvfb on Xorg 7.2. So in that case |
| you probably should restart it with something like this: "Xvfb :1 -cc |
| 4 -screen 0 1280x1024x24". It should be possible for x11vnc to handle |
| DirectColor, but this hasn't been implemented due to its rare usage. |
| |
| You may also see this problem on an X display with a TrueColor default |
| visual where an application chooses a DirectColor visual for its |
| window(s). It seems the application also needs to install its own |
| colormap for the visual for the colors to be messed up in x11vnc. One |
| can make xwud do this for example. |
| |
| |
| Q-26: How do I figure out the window id to supply to the -id windowid |
| option? |
| |
| Run the xwininfo program in a terminal. It will ask you to click on |
| the desired application window. After clicking, it will print out much |
| information, including the window id (e.g. 0x6000010.) Also, the |
| visual and depth of the window printed out is often useful in |
| debugging x11vnc color problems. |
| |
| Also, as of Dec/2004 you can use "-id pick" to have x11vnc run |
| xwininfo(1) for you and after you click the window it extracts the |
| windowid. Besides "pick" there is also "id:root" to allow you to go |
| back to root window when doing remote-control. |
| |
| |
| Q-27: Why don't menus or other transient windows come up when I am |
| using the -id windowid option to view a single application window? |
| |
| This is related to the behavior of the XGetImage(3X11) and |
| XShmGetImage() interfaces regarding backingstore, saveunders, etc. The |
| way the image is retrieved depends on some aspects of how the X server |
| maintains the display image data and whether other windows are |
| clipping or obscuring it. See the XGetImage(3X11) man page for more |
| details. If you disable BackingStore and SaveUnders in the X server |
| you should be able to see these transient windows. |
| |
| If things are not working and you still want to do the single window |
| polling, try the -sid windowid option ("shifted" windowid.) |
| |
| Update: as of Nov/2009 in the 0.9.9 x11vnc development tarball, there |
| is an experimental Application Sharing mode that improves upon the |
| -id/-sid single window sharing: -appshare (run "x11vnc -appshare |
| -help" for more info.) It is still very primitive and approximate, but |
| at least it displays multiple top-level windows. |
| |
| |
| Q-28: My X display is depth 24 at 24bpp (instead of the normal depth |
| 24 at 32bpp.) I'm having lots of color and visual problems with x11vnc |
| and/or vncviewer. What's up? |
| |
| First off, depth 24 at 24bpp (bpp=bits-per-pixel) is fairly uncommon |
| and can cause problems in general. It also can be slower than depth 24 |
| at 32bpp. You might want to switch to 32bpp (for XFree86 see the |
| "-fbbpp 32", DefaultFbBpp, FbBpp and related options.) Perhaps you |
| have 24bpp because the video memory of the machine is low and the |
| screen wouldn't fit in video RAM at 32bpp. For this case depth 16 at |
| 16bpp might be an acceptable option. |
| |
| In any event x11vnc should handle depth 24 at 24bpp (although |
| performance may be slower, and you may need to use the ZRLE encoding |
| instead of Tight.) There are some caveats involving the viewer |
| however: |
| |
| The RealVNC Unix viewer cannot handle 24bpp from the server, it will |
| say: "main: setPF: not 8, 16 or 32 bpp?" and exit. I have not checked |
| the RealVNC Windows viewer. |
| |
| So you need to use the TightVNC Unix viewer. However there are some |
| problems with that too. It seems libvncserver does not do 24bpp |
| correctly with the Tight encoding. The colors and screen ultimately |
| get messed up. So you have to use a different encoding with the |
| TightVNC vncviewer, try "zlib", "hextile", or one of the other |
| encodings (e.g. vncviewer -encodings "zlib hextile" ....) I have not |
| checked the TightVNC or UltraVNC Windows viewers. |
| |
| It appears the older RealVNC Unix viewers (e.g. 3.3.3 and 3.3.7) can |
| handle 24bpp from the server, so you may want to use those. They |
| evidently request 32 bpp and libvncserver obliges. |
| |
| Update: as of Apr/2006 you can use the -24to32 option to have x11vnc |
| dynamically transform the 24bpp pixel data to 32bpp. This extra |
| transformation could slow things down further however. |
| |
| Now coming the opposite direction if you are running the vncviewer on |
| the 24bpp display, TightVNC will fail with "Can't cope with 24 |
| bits-per-pixel. Sorry." and RealVNC will fail with "main: Error: |
| couldn't find suitable pixmap format" so evidently you cannot use |
| 24bpp for the vncviewers to work on that X display. |
| |
| Note, however, that the Unix viewer in the Enhanced TightVNC Viewer |
| (SSVNC) project can handle 24bpp X displays. It does this by |
| requesting a 16bpp pixel format (or 8bpp if the -bgr233 option has |
| been supplied) from the VNC server, and translates that to 24bpp |
| locally. |
| [Xterminals] |
| |
| Q-29: Can I use x11vnc to view and interact with an Xterminal (e.g. |
| NCD) that is not running UNIX and so x11vnc cannot be run on it |
| directly? |
| |
| You can, but it will likely be very wasteful of network bandwidth |
| since you will be polling the X display over the network as opposed to |
| over the local hardware. To do this, run x11vnc on a UNIX machine as |
| close as possible network-wise (e.g. same switch) to the Xterminal |
| machine. Use the -display option to point the display to that of the |
| Xterminal (you'll of course need basic X11 permission to do that) and |
| finally supply the -noshm option (this enables the polling over the |
| network.) |
| |
| If the Xterminal's X display is open to the network for connections, |
| you might use something like "-display xterm123:0". If you are trying |
| to do this via an SSH tunnel (assuming you can actually ssh into the |
| Xterminal) it will be a little tricky (either use the ssh "-R" option |
| or consider ssh-ing in the other direction.) In all cases the X11 |
| permissions need to allow the connection. |
| |
| The response will likely be sluggish (maybe only one "frame" per |
| second.) This mode is not recommended except for "quick checks" of |
| hard to get to X servers. Use something like "-wait 150" to cut down |
| on the polling rate. You may also need -flipbyteorder if the colors |
| get messed up due to endian byte order differences. |
| |
| Q-30: How do I get my X permissions (MIT-MAGIC-COOKIE file) correct |
| for a Unix/Linux machine acting as an Xterminal? |
| |
| If the X display machine is a traditional Xterminal (where the X |
| server process runs on the Xterminal box, but all of the X client |
| applications (firefox, etc) run on a central server (aka "terminal |
| server")), you will need to log into the Xterminal machine (i.e. get a |
| shell running there) and then start the x11vnc program. If the |
| Xterminal Linux/Unix machine is stripped down (e.g. no users besides |
| root) that may be difficult. |
| |
| The next problem is the login Display Manager (e.g. gdm, kdm), and |
| hence the MIT-MAGIC-COOKIE auth files, are on the central server and |
| not on the Xterminal box where the X server and x11vnc processes are. |
| |
| So unless X permissions are completely turned off (e.g. "xhost +"), to |
| run the x11vnc process on the Xterminal box the MIT-MAGIC-COOKIE auth |
| file data (XAUTHORITY or $HOME/.Xauthority) must be accessible by or |
| copied to the Xterminal. If $HOME/.Xauthority is exported via NFS |
| (this is insecure of course, but has been going on for decades), then |
| x11vnc can simply pick it up via NFS (you may need to use the -auth |
| option to point to the correct file.) Other options include copying |
| the auth file using scp, or something like: |
| central-server> xauth nextract - xterm123:0 | ssh xterm123 xauth nmerge - |
| |
| and then, say, ssh from central-server to xterm123 to start x11vnc. |
| Here "xterm123" refers to the computer acting as the Xterminal and |
| "central-server" is the terminal server. You can use "xauth -f |
| /path/to/cookie-file list" to examine the contents of the cookie(s) in |
| a file "/path/to/cookie-file". See the xauth(1) manpage for more |
| details. |
| |
| If the display name in the cookie file needs to be changed between the |
| two hosts, see this note on the "xauth add ..." command. |
| |
| A less secure option is to run something like "xhost +127.0.0.1" while |
| sitting at the Xterminal box to allow cookie-free local access for |
| x11vnc. You can run "xhost -127.0.0.1" after x11vnc connects if you |
| want to go back to the original permissions. |
| |
| If the Xterminal is really stripped down and doesn't have any user |
| accounts, NFS, etc. you'll need to contact your system administrator |
| to set something up. It can be done!!! Some Xterminal projects have |
| actually enabled "run locally" facilities for the running of an |
| occasional app more efficiently locally on the Xterminal box (e.g. |
| realplayer.) |
| |
| Not recommended, but as a last resort, you could have x11vnc poll the |
| Xterminal Display over the network. For this you would run a "x11vnc |
| -noshm ..." process on the central-server (and hope the network admin |
| doesn't get angry...) |
| |
| Note: use of Display Manager (gdm, kdm, ...) auth cookie files (i.e. |
| from /var/..., /tmp/..., or elsewhere) may require modification via |
| xauth(1) to correctly include the display x11vnc refers to (e.g. |
| "xauth -f cookie-file add :0 . 45be51ae2ce9dfbacd882ab3ef8e96b1", |
| where the "45be51..." cookie value was found from an "xauth -f |
| /path/to/original/cookie-file list") or other reasons. See xauth(1) |
| manpage for full details on how to transfer an MIT-MAGIC-COOKIE |
| between machines and displays. |
| |
| VNCviewer performance on Xterminals: This isn't related to x11vnc on |
| Xterminals, but we mention it here anyway because of the similar |
| issues. If you are on an Xterminal and want to use vncviewer to |
| connect to a VNC server somewhere, then performance would be best if |
| you ran the viewer on the Xterminal box. Otherwise, (i.e. running the |
| viewer process on the central-server) all of the vncviewer screen |
| drawing is done more inefficiently over the network. Something to |
| consider, especially on a busy network. (BTW, this has all of the |
| above permission, etc, problems: both vncviewer and x11vnc are X |
| client apps desired to be run on the Xterminal box.) |
| |
| [Sun Rays] |
| |
| Q-31: I'm having trouble using x11vnc with my Sun Ray session. |
| |
| The Sun Ray technology is a bit like "VNC done in hardware" (the Sun |
| Ray terminal device, DTU, playing the role of the vncviewer.) |
| Completely independent of that, the SunRay user's session is still an |
| X server that speaks the X11 protocol and so x11vnc simply talks to |
| the X server part to export the SunRay desktop to any place in the |
| world (i.e. not only to a Sun Ray terminal device), creating a sort of |
| "Soft Ray". Please see this discussion of Sun Ray issues for solutions |
| to problems. |
| |
| Also see the Sun Ray Remote Control Toolkit that uses x11vnc. |
| |
| [Remote Control] |
| |
| Q-32: How do I stop x11vnc once it is running in the background? |
| |
| As of Dec/2004 there is a remote control feature. It can change a huge |
| number of parameters on the fly: see the -remote and -query options. |
| To shut down the running x11vnc server just type "x11vnc -R stop". To |
| disconnect all clients do "x11vnc -R disconnect:all", etc. |
| |
| If the -forever option has not been supplied, x11vnc will |
| automatically exit after the first client disconnects. In general if |
| you cannot use the remote control, then you will have to kill the |
| x11vnc process This can be done via: "kill NNNNN" (where NNNNN is the |
| x11vnc process id number found from ps(1)), or "pkill x11vnc", or |
| "killall x11vnc" (Linux only.) |
| |
| If you have not put x11vnc in the background via the -bg option or |
| shell & operator, then simply press Ctrl-C in the shell where x11vnc |
| is running to stop it. |
| |
| Potential Gotcha: If somehow your Keypress of Ctrl-C went through |
| x11vnc to the Xserver that then delivered it to x11vnc it is possible |
| one or both of the Ctrl or C keys will be left stuck in the pressed |
| down state in the Xserver. Tapping the stuck key (either via a new |
| x11vnc or at the physical console) will release it from the stuck |
| state. If the keyboard seems to be acting strangely it is often fixed |
| by tapping Ctrl, Shift, and Alt. Alternatively, the -clear_mods option |
| and -clear_keys option can be used to release pressed keys at startup |
| and exit. The option -clear_all will also try to unset Caps_Lock, |
| Num_Lock, etc. |
| |
| |
| Q-33: Can I change settings in x11vnc without having to restart it? |
| Can I remote control it? |
| |
| Look at the -remote (an alias is -R) and -query (an alias is -Q) |
| options added in Dec/2004. They allow nearly everything to be changed |
| dynamically and settings to be queried. Examples: "x11vnc -R shared", |
| "x11vnc -R forever", "x11vnc -R scale:3/4", "x11vnc -Q modtweak", |
| "x11vnc -R stop", "x11vnc -R disconnect:all", etc.. |
| |
| These commands do not start a x11vnc server, but rather communicate |
| with one that is already running. The X display (X11VNC_REMOTE |
| property) is used as the communication channel, so the X permissions |
| and DISPLAY must be set up correctly for communication to be possible. |
| |
| There is also a simple Tcl/Tk gui based on this remote control |
| mechanism. See the -gui option for more info. You will need to have |
| Tcl/Tk (i.e. /usr/bin/wish) installed for it to work. It can also run |
| in the system tray: "-gui tray" or as a standalone small icon window: |
| "-gui icon". Use "-gui tray=setpass" for a naive user "Share My |
| Desktop" mode. |
| |
| [Security and Permissions] |
| |
| Q-34: How do I create a VNC password for use with x11vnc? |
| |
| You may already have one in $HOME/.vnc/passwd if you have used, say, |
| the vncserver program from the regular RealVNC or TightVNC packages |
| (i.e. launching the Xvnc server.) Otherwise, you could use the |
| vncpasswd(1) program from those packages. |
| |
| As of Jun/2004 x11vnc supports the -storepasswd "pass" "file" option, |
| which is the same functionality of storepasswd. Be sure to quote the |
| "pass" if it contains shell meta characters, spaces, etc. Example: |
| x11vnc -storepasswd 'sword*fish' $HOME/myvncpasswd |
| |
| You then use the password via the x11vnc option: "-rfbauth |
| $HOME/myvncpasswd" |
| |
| As of Jan/2006 if you do not supply any arguments: |
| x11vnc -storepasswd |
| |
| you will be prompted for a password to save to ~/.vnc/passwd (your |
| keystrokes when entering the password will not be echoed to the |
| screen.) If you supply one argument, e.g. "x11vnc -storepasswd |
| ~/.mypass", the password you are prompted for will be stored in that |
| file. |
| |
| x11vnc also has the -passwdfile and -passwd/-viewpasswd plain text |
| (i.e. not obscured like the -rfbauth VNC passwords) password options. |
| |
| You can use the -usepw option to automatically use any password file |
| you have in ~/.vnc/passwd or ~/.vnc/passwdfile (the latter is used |
| with the -passwdfile option.) |
| |
| x11vnc -usepw -display :0 ... |
| |
| If neither file exists you are prompted to store a password in |
| ~/.vnc/passwd. If a password file cannot be found or created x11vnc |
| exits immediately. An admin may want to set it up this way for users |
| who do not know better. |
| |
| |
| Q-35: Can I make it so -storepasswd doesn't show my password on the |
| screen? |
| |
| You can use the vncpasswd program from RealVNC or TightVNC mentioned |
| above. As of Jan/2006 the -storepasswd option without any arguments |
| will not echo your password as you type it and save the file to |
| ~/.vnc/passwd: |
| # x11vnc -storepasswd |
| Enter VNC password: |
| Verify password: |
| Write password to /home/myname/.vnc/passwd? [y]/n |
| Password written to: /home/myname/.vnc/passwd |
| |
| You can also give it an alternate filename, e.g. "x11vnc -storepasswd |
| ~/.mypass" |
| |
| |
| Q-36: Can I have two passwords for VNC viewers, one for full access |
| and the other for view-only access to the display? |
| |
| Yes, as of May/2004 there is the -viewpasswd option to supply the |
| view-only password. Note the full-access password option -passwd must |
| be supplied at the same time. E.g.: -passwd sword -viewpasswd fish. |
| |
| To avoid specifying the passwords on the command line (where they |
| could be observed via the ps(1) command by any user) you can use the |
| -passwdfile option to specify a file containing plain text passwords. |
| Presumably this file is readable only by you, and ideally it is |
| located on the machine x11vnc is run on (to avoid being snooped on |
| over the network.) The first line of this file is the full-access |
| password. If there is a second line in the file and it is non-blank, |
| it is taken as the view-only password. (use "__EMPTY__" to supply an |
| empty one.) |
| |
| View-only passwords currently do not work for the -rfbauth password |
| option (standard VNC password storing mechanism.) FWIW, note that |
| although the output (usually placed in $HOME/.vnc/passwd) by the |
| vncpasswd or storepasswd programs (or from x11vnc -storepasswd) looks |
| encrypted they are really just obscured to avoid "casual" password |
| stealing. It takes almost no skill to figure out how to extract the |
| plain text passwords from $HOME/.vnc/passwd since it is very |
| straight-forward to work out what to do from the VNC source code. |
| |
| |
| Q-37: Can I have as many full-access and view-only passwords as I |
| like? |
| |
| Yes, as of Jan/2006 in the libvncserver CVS the -passwdfile option has |
| been extended to handle as many passwords as you like. You put the |
| view-only passwords after a line __BEGIN_VIEWONLY__. |
| |
| You can also easily annotate and comment out passwords in the file. |
| You can have x11vnc re-read the file dynamically when it is modified. |
| |
| |
| Q-38: Does x11vnc support Unix usernames and passwords? Can I further |
| limit the set of Unix usernames who can connect to the VNC desktop? |
| Update: as of Feb/2006 x11vnc has the -unixpw option that does this |
| outside of the VNC protocol and libvncserver. The standard su(1) |
| program is used to validate the user's password. A familiar "login:" |
| and "Password:" dialog is presented to the user on a black screen |
| inside the vncviewer. The connection is dropped if the user fails to |
| supply the correct password in 3 tries or does not send one before a |
| 25 second timeout. Existing clients are view-only during this period. |
| A list of allowed Unix usernames may also be supplied along with |
| per-user settings. |
| |
| There is also the -unixpw_nis option for non-shadow-password |
| (typically NIS environments, hence the name) systems where the |
| traditional getpwnam() and crypt() functions are used instead of |
| su(1). The encrypted user passwords must be accessible to the user |
| running x11vnc in -unixpw_nis mode, otherwise the logins will always |
| fail even when the correct password is supplied. See ypcat(1) and |
| shadow(5). |
| |
| Two settings are enforced in the -unixpw and -unixpw_nis modes to |
| provide extra security: the 1) -localhost and 2) -stunnel or -ssl |
| options. Without these one might send the Unix username and password |
| data in clear text over the network which is a very bad idea. They can |
| be relaxed if you want to provide encryption other than stunnel or |
| -ssl (the constraint is automatically relaxed if SSH_CONNECTION is set |
| and indicates you have ssh-ed in, however the -localhost requirement |
| is still enforced.) |
| |
| The two -unixpw modes have been tested on Linux, Solaris, Mac OS X, |
| HP-UX, AIX, Tru64, FreeBSD, OpenBSD, and NetBSD. Additional testing is |
| appreciated. For the last 4 it appears that su(1) will not prompt for |
| a password if su-ing to oneself. Since x11vnc requires a password |
| prompt from su, x11vnc forces those logins to fail even when the |
| correct password is supplied. On *BSD it appears this can be corrected |
| by removing the pam_self.so entry in /etc/pam.d/su. |
| |
| |
| Previous older discussion (prior to the -unixpw option): |
| |
| Until the VNC protocol and libvncserver support this things will be |
| approximate at best. |
| |
| One approximate method involves starting x11vnc with the -localhost |
| option. This basically requires the viewer user to log into the |
| workstation where x11vnc is running via their Unix username and |
| password, and then somehow set up a port redirection of his vncviewer |
| connection to make it appear to emanate from the local machine. As |
| discussed above, ssh is useful for this: "ssh -L 5900:localhost:5900 |
| user@hostname ..." See the ssh wrapper scripts mentioned elsewhere on |
| this page. stunnel does this as well. |
| |
| Of course a malicious user could allow other users to get in through |
| his channel, but that is a problem with every method. Another thing to |
| watch out for is a malicious user on the viewer side (where ssh is |
| running) trying to sneak in through the ssh port redirection there. |
| |
| Regarding limiting the set of Unix usernames who can connect, the |
| traditional way would be to further require a VNC password to supplied |
| (-rfbauth, -passwd, etc) and only tell the people allowed in what the |
| VNC password is. A scheme that avoids a second password involves using |
| the -accept option that runs a program to examine the connection |
| information to determine which user is connecting from the local |
| machine. That may be difficult to do, but, for example, the program |
| could use the ident service on the local machine (normally ident |
| should not be trusted over the network, but on the local machine it |
| should be accurate: otherwise root has been compromised and so there |
| are more serious problems! Unfortunately recent Linux distros seem to |
| provide a random string (MD5 hash?) instead of the username.) An |
| example script passed in via -accept scriptname that deduces the Unix |
| username and limits who can be accepted might look something like |
| this: |
| #!/bin/sh |
| if [ "$RFB_CLIENT_IP" != "127.0.0.1" -o "$RFB_SERVER_IP" != "127.0.0.1" ]; then |
| exit 1 # something fishy... reject it. |
| fi |
| user=`echo "$RFB_CLIENT_PORT, $RFB_SERVER_PORT" | nc -w 1 $RFB_CLIENT_IP 113 \ |
| | grep 'USERID.*UNIX' | head -n 1 | sed -e 's/[\r ]//g' | awk -F: '{pri |
| nt $4}'` |
| |
| for okuser in fred barney wilma betty |
| do |
| if [ "X$user" = "X$okuser" ]; then |
| exit 0 # accept it |
| fi |
| done |
| exit 1 # reject it |
| |
| For this to work with ssh port redirection, the ssh option |
| UsePrivilegeSeparation must be enabled otherwise the userid will |
| always be "root". |
| |
| Here is a similar example based on Linux netstat(1) output: |
| #!/bin/sh |
| # |
| # accept_local_netstat: x11vnc -accept command to accept a local |
| # vncviewer connection from acceptable users. Linux netstat -nte is used. |
| |
| PATH=/bin:/usr/bin:$PATH; export PATH; # set to get system utils |
| |
| allowed="`id -u fred`"; # add more user numbers if desired. |
| |
| # check required settings |
| ok=1 |
| if [ "X$allowed" = "X" ]; then |
| ok=0; # something wrong with allowed list |
| fi |
| if [ "X$RFB_CLIENT_IP" != "X127.0.0.1" -o "X$RFB_SERVER_IP" != "X127.0.0.1" ]; |
| then |
| ok=0; # connection not over localhost |
| fi |
| if [ "$RFB_CLIENT_PORT" -le 0 -o "$RFB_SERVER_PORT" -le 0 ]; then |
| ok=0; # something wrong with tcp port numbers |
| fi |
| if [ "$ok" = 0 ]; then |
| echo "$0: invalid setting:" 1>&2 |
| env | grep ^RFB | sort 1>&2 |
| exit 1 |
| fi |
| |
| # Linux netstat -nte: |
| # Proto Recv-Q Send-Q Local Address Foreign Address State |
| User Inode |
| # 0 0 0 RFB_CLIENT RFB_SERVER ESTABLISHED |
| nnnn .... |
| # |
| user=`netstat -nte | grep ESTABLISHED \ |
| | grep " $RFB_CLIENT_IP:$RFB_CLIENT_PORT *$RFB_SERVER_IP:$RFB_SERVER_P |
| ORT "` |
| |
| echo "netstat match: $user" 1>&2 |
| user=`echo "$user" | head -n 1 | sed -e 's/^.*ESTABLISHED/ /' | awk '{print $1} |
| '` |
| |
| ok=0 |
| for u in $allowed |
| do |
| if [ "X$user" = "X$u" ]; then |
| ok=1 |
| break |
| fi |
| done |
| |
| if [ "X$ok" = "X1" ]; then |
| echo "$0: user accepted: '$user'" 1>&2 |
| exit 0 |
| else |
| echo "$0: user '$user' invalid:" 1>&2 |
| echo "$0: allowed: $allowed" 1>&2 |
| env | grep ^RFB | sort 1>&2 |
| exit 1 |
| fi |
| |
| |
| Q-39: Can I supply an external program to provide my own custom login |
| method (e.g. Dynamic/One-time passwords or non-Unix (LDAP) usernames |
| and passwords)? |
| Yes, there are several possibilities. For background see the FAQ on |
| the -accept where an external program may be run to decide if a VNC |
| client should be allowed to try to connect and log in. If the program |
| (or local user prompted by a popup) answers "yes", then -accept |
| proceeds to the normal VNC and x11vnc authentication methods, |
| otherwise the connection is dropped. |
| |
| To provide more direct coupling to the VNC client's username and/or |
| supplied password the following options were added in Sep/2006: |
| * -unixpw_cmd command |
| * -passwdfile cmd:command |
| * -passwdfile custom:command |
| |
| In each case "command" is an external command run by x11vnc. You |
| supply it. For example, it may couple to your LDAP system or other |
| servers you set up. |
| |
| For -unixpw_cmd the normal -unixpw Login: and Password: prompts are |
| supplied to the VNC viewer and the strings the client returns are then |
| piped into "command" as the first two lines of its standard input. If |
| the command returns success, i.e. exit(0), the VNC client is accepted, |
| otherwise it is rejected. |
| |
| For "-passwdfile cmd:command" the command is run and it returns a |
| password list (like a password file, see the -passwdfile read:filename |
| mode.) Perhaps a dynamic, one-time password is retrieved from a server |
| this way. |
| |
| For "-passwdfile custom:command" one gets complete control over the |
| VNC challenge-response dialog with the VNC client. x11vnc sends out a |
| string of random bytes (16 by the VNC spec) and the client returns the |
| same number of bytes in a way the server can verify only the |
| authorized user could have created. The VNC protocol specifies DES |
| encryption with a password. If you are willing to modify the VNC |
| viewers, you can have it be anything you want, perhaps a less |
| crackable MD5 hash scheme or one-time pad. Your program will read from |
| its standard input the size of the challenge-response followed by a |
| newline, then the challenge bytes followed by the response bytes. If |
| your command then returns success, i.e. exit(0), the VNC client is |
| accepted, otherwise it is rejected. |
| |
| In all cases the "RFB_*" environment variables are set as under |
| -accept. These variables can provide useful information for the |
| externally supplied program to use. |
| |
| |
| Q-40: Why does x11vnc exit as soon as the VNC viewer disconnects? And |
| why doesn't it allow more than one VNC viewer to connect at the same |
| time? |
| |
| These defaults are simple safety measures to avoid someone unknowingly |
| leaving his X11 desktop exposed (to the internet, say) for long |
| periods of time. Use the -forever option (aka -many) to have x11vnc |
| wait for more connections after the first client disconnects. Use the |
| -shared option to have x11vnc allow multiple clients to connect |
| simultaneously. |
| |
| Recommended additional safety measures include using ssh (see above), |
| stunnel, -ssl, or a VPN to authenticate and encrypt the viewer |
| connections or to at least use the -rfbauth passwd-file option to use |
| VNC password protection (or -passwdfile) It is up to YOU to apply |
| these security measures, they will not be done for you automatically. |
| |
| |
| Q-41: Can I limit which machines incoming VNC clients can connect |
| from? |
| |
| Yes, look at the -allow and -localhost options to limit connections by |
| hostname or IP address. E.g. |
| x11vnc -allow 192.168.0.1,192.168.0.2 |
| |
| for those two hosts or |
| x11vnc -allow 192.168.0. |
| |
| for a subnet. For individual hosts you can use the hostname instead of |
| the IP number, e.g.: "-allow snoopy", and "-allow darkstar,wombat". |
| Note that -localhost achieves the same thing as "-allow 127.0.0.1" |
| |
| For more control, build libvncserver with libwrap support |
| (tcp_wrappers) and then use /etc/hosts.allow See hosts_access(5) for |
| complete details. |
| |
| |
| Q-42: How do I build x11vnc/libvncserver with libwrap (tcp_wrappers) |
| support? |
| |
| Here is one way to pass this information to the configure script: |
| env CPPFLAGS=-DUSE_LIBWRAP LDFLAGS=-lwrap ./configure |
| |
| then run make as usual. This requires libwrap and its development |
| package (tcpd.h) to be installed on the build machine. If additional |
| CPPFLAGS or LDFLAGS options are needed supply them as well using |
| quotes. |
| |
| The resulting x11vnc then uses libwrap/tcp_wrappers for connections. |
| The service name you will use in /etc/hosts.allow and /etc/hosts.deny |
| is "vnc", e.g.: |
| vnc: 192.168.100.3 .example.com |
| |
| Note that if you run x11vnc out of inetd you do not need to build |
| x11vnc with libwrap support because the /usr/sbin/tcpd reference in |
| /etc/inetd.conf handles the tcp_wrappers stuff. |
| |
| |
| Q-43: Can I have x11vnc only listen on one network interface (e.g. |
| internal LAN) rather than having it listen on all network interfaces |
| and relying on -allow to filter unwanted connections out? |
| |
| As of Mar/2005 there is the "-listen ipaddr" option that enables this. |
| For ipaddr either supply the desired network interface's IP address |
| (or use a hostname that resolves to it) or use the string "localhost". |
| For additional filtering simultaneously use the "-allow host1,..." |
| option to allow only specific hosts in. |
| |
| This option is useful if you want to insure that no one can even begin |
| a dialog with x11vnc from untrusted network interfaces (e.g. ppp0.) |
| The option -localhost now implies "-listen localhost" since that is |
| what most people expect it to do. |
| |
| |
| Q-44: Now that -localhost implies listening only on the loopback |
| interface, how I can occasionally allow in a non-localhost via the -R |
| allowonce remote control command? |
| |
| To do this specify "-allow localhost". Unlike -localhost this will |
| leave x11vnc listening on all interfaces (but of course only allowing |
| in local connections, e.g. ssh redirs.) Then you can later run "x11vnc |
| -R allowonce:somehost" or use to gui to permit a one-shot connection |
| from a remote host. |
| |
| |
| Q-45: Can I fine tune what types of user input are allowed? E.g. have |
| some users just be able to move the mouse, but not click or type |
| anything? |
| |
| As of Feb/2005, the -input option allows you to do this. "K", "M", |
| "B", "C", and "F" stand for Keystroke, Mouse-motion, Button-clicks, |
| Clipboard, and File-Transfer, respectively. The setting: "-input M" |
| makes attached viewers only able to move the mouse. "-input KMBC,M" |
| lets normal clients do everything and enables view-only clients to |
| move the mouse. |
| |
| These settings can also be applied on a per-viewer basis via the |
| remote control mechanism or the GUI. E.g. x11vnc -R input:hostname:M |
| |
| |
| Q-46: Can I prompt the user at the local X display whether the |
| incoming VNC client should be accepted or not? Can I decide to make |
| some clients view-only? How about running an arbitrary program to make |
| the decisions? |
| |
| Yes, look at the "-accept command" option, it allows you to specify an |
| external command that is run for each new client. (use quotes around |
| the command if it contains spaces, etc.) If the external command |
| returns 0 (success) the client is accepted, otherwise with any other |
| return code the client is rejected. See below how to also accept |
| clients view-only. |
| |
| The external command will have the RFB_CLIENT_IP environment variable |
| set to the client's numerical IP address, RFB_CLIENT_PORT its port |
| number. Similarly for RFB_SERVER_IP and RFB_SERVER_PORT to allow |
| identification of the tcp virtual circuit. DISPLAY will be set to that |
| of the X11 display being polled. Also, RFB_X11VNC_PID is set to the |
| x11vnc process id (e.g. in case you decided to kill it), RFB_CLIENT_ID |
| will be an id number, and RFB_CLIENT_COUNT the number of other clients |
| currently connected. RFB_MODE will be "accept". |
| |
| Built-in Popup Window: As a special case, "-accept popup" will |
| instruct x11vnc to create its own simple popup window. To accept the |
| client press "y" or click mouse on the "Yes" button. To reject the |
| client press "n" or click mouse on the "No" button. To accept the |
| client View-only, press "v" or click mouse on the "View" button. If |
| the -viewonly option has been supplied, the "View" action will not be |
| present: the whole display is view only in that case. |
| |
| The popup window times out after 120 seconds, to change this behavior |
| use "-accept popup:N" where N is the number of seconds (use 0 for no |
| timeout.) More tricks: "-accept popupmouse" will only take mouse click |
| responses, while "-accept popupkey" will only take keystroke responses |
| (popup takes both.) After any of the 3 popup keywords you can supply a |
| position of the window: +N+M, (the default is to center the window) |
| e.g. -accept popupmouse+10+10. |
| |
| Also as a special case "-accept xmessage" will run the xmessage(1) |
| program to prompt the user whether the client should be accepted or |
| not. This requires that you have xmessage installed and available via |
| PATH. In case it is not already on your system, the xmessage program |
| is available at ftp://ftp.x.org/ |
| (End of Built-in Popup Window:) |
| |
| To include view-only decisions for the external commands, prefix the |
| command something like this: "yes:0,no:*,view:3 mycommand ..." This |
| associates the three actions: yes(accept), no(reject), and |
| view(accept-view-only), with the numerical return (i.e. exit()) codes. |
| Use "*" instead of a number to set the default action (e.g. in case |
| the external command returns an unexpected return code.) |
| |
| Here is an example -accept script called accept_or_lock. It uses |
| xmessage and xlock (replace with your screen lock command, maybe it is |
| "xscreensaver-command -lock", or kdesktop_lock, or "dtaction |
| LockDisplay".) It will prompt the user at the X display whether to |
| accept, reject, or accept view-only the client, but if the prompt |
| times out after 60 seconds the screen is locked and the VNC client is |
| accepted. This allows the remote access when no one is at the display. |
| #!/bin/sh |
| # |
| # accept_or_lock: prompt user at X display whether to accept an incoming |
| # VNC connection. If timeout expires, screen is locked |
| # and the VNC viewer is accepted (allows remote access |
| # when no one is sitting at the display.) |
| # |
| # usage: x11vnc ... -forever -accept 'yes:0,no:*,view:4 accept_or_lock' |
| # |
| xmessage -buttons yes:2,no:3,view-only:4 -center \ |
| -timeout 60 "x11vnc: accept connection from $RFB_CLIENT_IP?" |
| rc=$? |
| if [ $rc = 0 ]; then |
| xlock & # or "xlock -mode blank" for no animations. |
| sleep 5 |
| exit 0 |
| elif [ $rc = 2 ]; then |
| exit 0 |
| elif [ $rc = 4 ]; then |
| exit 4 |
| fi |
| exit 1 |
| |
| Stefan Radman has written a nice dtksh script dtVncPopup for use in |
| CDE environments to do the same sort of thing. Information on how to |
| use it is found at the top of the file. He encourages you to provide |
| feedback to him to help improve the script. |
| |
| Note that in all cases x11vnc will block while the external command or |
| popup is being run, so attached clients will not receive screen |
| updates, etc during this period. |
| |
| To run a command when a client disconnects, use the "-gone command" |
| option. This is for the user's convenience only: the return code of |
| the command is not interpreted by x11vnc. The same environment |
| variables are set as in "-accept command" (except that RFB_MODE will |
| be "gone".) |
| |
| As of Jan/2006 the "-afteraccept command" option will run the command |
| only after the VNC client has been accepted and authenticated. Like |
| -gone the return code is not interpreted. RFB_MODE will be |
| "afteraccept".) |
| |
| |
| Q-47: I start x11vnc as root because it is launched via inetd(8) or a |
| display manager like gdm(1). Can I have x11vnc later switch to a |
| different user? |
| |
| As of Feb/2005 x11vnc has the -users option that allows things like |
| this. Please read the documentation on it (also in the x11vnc -help |
| output) carefully for features and caveats. It's use can often |
| decrease security unless care is taken. |
| |
| BTW, a nice use of it is "-users +nobody" that switches to the Unix |
| user nobody right after connections to the X display are established. |
| |
| In any event, while running x11vnc as root, remember it comes with no |
| warranty ;-). |
| |
| |
| Q-48: I use a screen-lock when I leave my workstation (e.g. |
| xscreensaver or xlock.) When I remotely access my workstation desktop |
| via x11vnc I can unlock the desktop fine, but I am worried people will |
| see my activities on the physical monitor. What can I do to prevent |
| this, or at least make it more difficult? |
| |
| Probably most work environments would respect your privacy if you |
| powered off the monitor. Also remember if people have physical access |
| to your workstation they basically can do anything they want with it |
| (e.g. install a backdoor for later use, etc.) |
| |
| In any event, as of Jun/2004 there is an experimental utility to make |
| it more difficult for nosey people to see your x11vnc activities. The |
| source for it is blockdpy.c The idea behind it is simple (but |
| obviously not bulletproof): when a VNC client attaches to x11vnc put |
| the display monitor in the DPMS "off" state, if the DPMS state ever |
| changes immediately start up the screen-lock program. The x11vnc user |
| will notice something is happening and think about what to do next |
| (while the screen is in a locked state.) |
| |
| This works (or at least has a chance of working) because if the |
| intruder moves the mouse or presses a key on the keyboard, the monitor |
| wakes up out of the DPMS off state, and this induces the screen lock |
| program to activate as soon as possible. Of course there are cracks in |
| this, the eavesdropper could detach your monitor and insert a non-DPMS |
| one, and there are race conditions. As mentioned above this is not |
| bulletproof. A really robust solution would likely require X server |
| and perhaps even video hardware support. |
| |
| The blockdpy utility is launched by the -accept option and told to |
| exit via the -gone option (the vnc client user should obviously |
| re-lock the screen before disconnecting!) Instructions can be found in |
| the source code for the utility at the above link. Roughly it is |
| something like this: |
| x11vnc ... -accept "blockdpy -bg -f $HOME/.bdpy" -gone "touch $HOME/.bdpy" |
| |
| but please read the top of the file. |
| |
| Update: As of Feb/2007 there is some builtin support for this: |
| -forcedpms and -clientdpms however, they are probably less robust than |
| the above blockdpy.c scheme, since if the person floods the physical |
| machine with mouse or pointer input he can usually see flashes of the |
| screen before the monitor is powered off again. See also the -grabkbd, |
| -grabptr, and -grabalways options. |
| |
| |
| Q-49: Can I have x11vnc automatically lock the screen when I |
| disconnect the VNC viewer? |
| |
| Yes, a user mentions he uses the -gone option under CDE to run a |
| screen lock program: |
| x11vnc -display :0 -forever -gone 'dtaction LockDisplay' |
| |
| Other possibilities are: |
| x11vnc -display :0 -forever -gone 'xscreensaver-command -lock' |
| x11vnc -display :0 -forever -gone 'kdesktop_lock' |
| x11vnc -display :0 -forever -gone 'xlock &' |
| x11vnc -display :0 -forever -gone 'xlock -mode blank &' |
| |
| Here is a scheme using the -afteraccept option (in version 0.8) to |
| unlock the screen after the first valid VNC login and to lock the |
| screen after the last valid VNC login disconnects: |
| x11vnc -display :0 -forever -shared -afteraccept ./myxlocker -gone ./myxlocke |
| r |
| |
| Where the script ./myxlocker is: |
| #!/bin/sh |
| |
| #/usr/bin/env | grep RFB_ | sort # for viewing RFB_* settings. |
| |
| if [ "X$RFB_MODE" = "Xafteraccept" ]; then |
| if [ "X$RFB_STATE" = "XNORMAL" ]; then # require valid login |
| if [ "X$RFB_CLIENT_COUNT" = "X1" ]; then |
| killall xlock # Linux only. |
| fi |
| fi |
| elif [ "X$RFB_MODE" = "Xgone" ]; then |
| if [ "X$RFB_STATE" = "XNORMAL" ]; then # require valid login |
| if [ "X$RFB_CLIENT_COUNT" = "X0" ]; then |
| xlock -mode blank & |
| fi |
| fi |
| fi |
| |
| Note the xlock option "-mode blank" to avoid animations. |
| |
| There is a problem if you have x11vnc running this way in -forever |
| mode and you hit Ctrl-C to stop it. The xlock (or other program) will |
| get killed too. To work around this make a little script called |
| setpgrp that looks like: |
| #!/usr/bin/perl |
| setpgrp(0, 0); |
| exec @ARGV; |
| |
| then use -gone "setpgrp xlock &", etc. |
| [Encrypted Connections] |
| |
| Q-50: How can I tunnel my connection to x11vnc via an encrypted SSH |
| channel between two Unix machines? |
| |
| See the description earlier on this page on how to tunnel VNC via SSH |
| from Unix to Unix. A number of ways are described along with some |
| issues you may encounter. |
| |
| Other secure encrypted methods exists, e.g. stunnel, IPSEC, various |
| VPNs, etc. |
| |
| See also the Enhanced TightVNC Viewer (SSVNC) page where much of this |
| is now automated. |
| |
| |
| Q-51: How can I tunnel my connection to x11vnc via an encrypted SSH |
| channel from Windows using an SSH client like Putty? |
| |
| Above we described how to tunnel VNC via SSH from Unix to Unix, you |
| may want to review it. To do this from Windows using Putty it would go |
| something like this: |
| * In the Putty dialog window under 'Session' enter the hostname or |
| IP number of the Unix machine with display to be viewed. |
| * Make sure the SSH protocol is selected and the server port is |
| correct. |
| * Under 'Connections/SSH/Tunnels' Add a Local connection with |
| 'Source port: 5900' and 'Destination: localhost:5900' |
| * Log into the remote machine by pressing 'Open' and supplying |
| username, password, etc. |
| * In that SSH shell, start up x11vnc by typing the command: x11vnc |
| -display :0 plus any other desired options (e.g. -localhost.) |
| * Finally, start up your VNC Viewer in Windows and enter |
| 'localhost:0' as the VNC server. |
| |
| You can keep all of the settings in a Putty 'Saved Session'. Also, |
| once everything is working, you can consider putting x11vnc -display |
| :0 (plus other cmdline options) in the 'Remote command' Putty setting |
| under 'Connections/SSH'. |
| |
| See also the Enhanced TightVNC Viewer (SSVNC) page where much of this |
| is now automated via the Putty plink utility. |
| |
| For extra protection feel free to run x11vnc with the -localhost and |
| -rfbauth/-passwdfile options. |
| |
| If the machine you SSH into via Putty is not the same machine with the |
| X display you wish to view (e.g. your company provides incoming SSH |
| access to a gateway machine), then you need to change the above Putty |
| dialog setting to: 'Destination: otherhost:5900', Once logged in, |
| you'll need to do a second login (ssh or rsh) to the workstation |
| machine 'otherhost' and then start up x11vnc on it. This can also be |
| automated by Chaining SSH's. |
| |
| As discussed above another option is to first start the VNC viewer in |
| "listen" mode, and then launch x11vnc with the "-connect localhost" |
| option to establish the reverse connection. In this case a Remote port |
| redirection (not Local) is needed for port 5500 instead of 5900 (i.e. |
| 'Source port: 5500' and 'Destination: localhost:5500' for a Remote |
| connection.) |
| |
| |
| Q-52: How can I tunnel my connection to x11vnc via an encrypted SSL |
| channel using an external tool like stunnel? |
| |
| It is possible to use a "lighter weight" encryption setup than SSH or |
| IPSEC. SSL tunnels such as stunnel (also stunnel.org) provide an |
| encrypted channel without the need for Unix users, passwords, and key |
| passphrases required for ssh (and at the other extreme SSL can also |
| provide a complete signed certificate chain of trust.) On the other |
| hand, since SSH is usually installed everywhere and firewalls often |
| let its port through, ssh is frequently the path of least resistance |
| (it also nicely manages public keys for you.) |
| |
| Update: As of Feb/2006 x11vnc has the options -ssl, -stunnel, and |
| -sslverify to provide integrated SSL schemes. They are discussed in |
| the Next FAQ (you probably want to skip to it now.) |
| |
| We include these non-built-in method descriptions below for historical |
| reference. They are handy because can be used to create SSL tunnels to |
| any VNC (or other type of) server. |
| |
| |
| Here are some basic examples using stunnel but the general idea for |
| any SSL tunnel utility is the same: |
| * Start up x11vnc and constrain it to listen on localhost. |
| * Then start up the SSL tunnel running on the same machine to |
| forward incoming connections to that x11vnc. |
| * Set up and run a similar SSL tunnel for the outgoing connection on |
| the VNC viewer machine pointing it to the SSL/x11vnc server. |
| * Optionally, set up server (or even client) public/private keys for |
| use in authenticating one side to the other. |
| * Finally, start the VNC Viewer and tell it to connect to the local |
| port (e.g. a vnc display localhost:0) where its outgoing SSL |
| tunnel is listening. |
| |
| We'll first use the stunnel version 3 syntax since it is the most |
| concise and Unixy. |
| |
| Start up x11vnc listening on port 5900: |
| x11vnc -display :0 -rfbport 5900 -localhost -bg -passwdfile ~/mypass |
| |
| Then start stunnel (version 3, not 4) with this command: |
| stunnel -d 5901 -r 5900 -p /path/to/stunnel.pem |
| |
| The above two commands are run on host "far-away.east". The |
| stunnel.pem is the self-signed PEM file certificate created when |
| stunnel is built. One can also create certificates signed by |
| Certificate Authorities or self-signed if desired using the x11vnc |
| utilities described there. |
| |
| SSL Viewers: Next, on the VNC viewer side we need an SSL tunnel to |
| encrypt the outgoing connection. The nice thing is any SSL tunnel can |
| be used because the protocol is a standard. For this example we'll |
| also use stunnel on the viewer side on Unix. First start up the |
| client-side stunnel (version 3, not 4): |
| stunnel -c -d localhost:5902 -r far-away.east:5901 |
| |
| Then point the viewer to the local tunnel on port 5902: |
| vncviewer -encodings "copyrect tight zrle hextile" localhost:2 |
| |
| That's it. Note that the ss_vncviewer script can automate this |
| easily, and so can the Enhanced TightVNC Viewer (SSVNC) package. |
| |
| Be sure to use a VNC password because unlike ssh by default the |
| encrypted SSL channel provides no authentication (only privacy.) With |
| some extra configuration one could also set up certificates to provide |
| authentication of either or both sides as well (and hence avoid |
| man-in-the-middle attacks.) See the stunnel and openssl documentation |
| and also the key management section for details. |
| |
| stunnel has also been ported to Windows, and there are likely others |
| to choose from for that OS. Much info for using it on Windows can be |
| found at the stunnel site and in this article The article also shows |
| the detailed steps to set up all the authentication certificates. (for |
| both server and clients, see also the x11vnc utilities that do this.) |
| The default Windows client setup (no certs) is simpler and only 4 |
| files are needed in a folder: stunnel.exe, stunnel.conf, libssl32.dll, |
| libeay32.dll. We used an stunnel.conf containing: |
| # stunnel.conf: |
| client = yes |
| options = ALL |
| [myvncssl] |
| accept = localhost:5902 |
| connect = far-away.east:5901 |
| |
| then double click on the stunnel.exe icon to launch it (followed by |
| pointing the VNC viewer to localhost:2). |
| |
| |
| stunnel inetd-like mode: |
| |
| As an aside, if you don't like the little "gap" of unencrypted TCP |
| traffic (and a localhost listening socket) on the local machine |
| between stunnel and x11vnc it can actually be closed by having stunnel |
| start up x11vnc in -inetd mode: |
| stunnel -p /path/to/stunnel.pem -P none -d 5900 -l ./x11vnc_sh |
| |
| Where the script x11vnc_sh starts up x11vnc: |
| #!/bin/sh |
| x11vnc -q -inetd -display :0 -passwdfile ~/mypass |
| |
| Note that this creates a separate x11vnc process for each incoming |
| connection (as any inetd x11vnc usage would), but for the case of |
| normally just one viewer at a time it should not be a big problem. |
| |
| |
| stunnel 4 syntax: |
| |
| Somewhat sadly, the stunnel version 4 syntax is not so amenable to the |
| command line or scripts. You need to create a config file with the |
| parameters. E.g.: |
| stunnel x11vnc.cfg |
| |
| Where the file x11vnc.cfg contains: |
| foreground = yes |
| pid = |
| cert = /path/to/stunnel.pem |
| [x11vnc_stunnel] |
| accept = 5901 |
| connect = 5900 |
| |
| One nice thing about version 4 is often the PEM file does not need to |
| be specified because stunnel finds it in its installed area. One other |
| gotcha the PEM file is usually only readable by root (it has the |
| private key afterall), so you'll need to relax the permissions or make |
| a copy that the user running x11vnc/stunnel can read. |
| |
| |
| SSL VNC Viewers: |
| |
| Regarding VNC viewers that "natively" do SSL unfortunately there do |
| not seem to be many. The SingleClick UltraVNC Java Viewer is SSL and |
| is compatible with x11vnc's -ssl option and stunnel.) Commercial |
| versions of VNC seem to have some SSL-like encryption built in, but we |
| haven't tried those either and they probably wouldn't work since their |
| (proprietary) SSL-like negotiation is likely embedded in the VNC |
| protocol unlike our case where it is external. |
| |
| Note: as of Mar/2006 libvncserver/x11vnc provides a SSL-enabled Java |
| applet that can be served up via the -httpdir or -http options when |
| -ssl is enabled. It will also be served via HTTPS via either the VNC |
| port (e.g. https://host:5900/) or a 2nd port via the -https option. |
| |
| In general current SSL VNC solutions are not particularly "seemless". |
| But it can be done, and with a wrapper script on the viewer side and |
| the -stunnel or -ssl option on the server side it works well and is |
| convenient. Here is a simple script ss_vncviewer that automates |
| running stunnel on the VNC viewer side on Unix a little more carefully |
| than the commands printed above. (One could probably do a similar |
| thing with a .BAT file on Windows in the stunnel folder.) |
| |
| Update Jul/2006: we now provide an Enhanced TightVNC Viewer (SSVNC) |
| package that starts up STUNNEL automatically along with some other |
| features. All binaries (stunnel, vncviewer, and some utilities) are |
| provided in the package. It works on Unix, Mac OS X, and Windows. |
| |
| |
| Q-53: Does x11vnc have built-in SSL tunneling? |
| |
| You can read about non-built-in methods in the Previous FAQ for |
| background. |
| |
| SSL tunnels provide an encrypted channel without the need for Unix |
| users, passwords, and key passphrases required for ssh (and at the |
| other extreme SSL can also provide a complete signed certificate chain |
| of trust.) On the other hand, since SSH is usually installed |
| everywhere and firewalls often let its port through, ssh is frequently |
| the path of least resistance. |
| |
| Built-in SSL x11vnc options: |
| |
| As of Feb/2006 the x11vnc -ssl option automates the SSL tunnel |
| creation on the x11vnc server side. An SSL-enabled Java Viewer applet |
| is also provided that can be served via HTTP or HTTPS to automate SSL |
| on the client side. |
| |
| The -ssl mode uses the www.openssl.org library if available at build |
| time. |
| |
| The mode requires an SSL certificate and key (i.e. .pem file.) These |
| are usually created via the openssl(1) program (in fact in for "-ssl" |
| (same as "-ssl SAVE") it will run openssl for you automatically.) So |
| the SSL is not completely "built-in" since this external tool needs to |
| be installed, but at least x11vnc runs it for you automatically. |
| |
| An -ssl example: |
| x11vnc -display :0 -ssl -passwdfile ~/mypass |
| |
| You'll get output like this: |
| 09/04/2006 19:27:35 Creating a self-signed PEM certificate... |
| 09/04/2006 19:27:35 |
| ... |
| |
| The SSL VNC desktop is: far-away.east:0 |
| PORT=5900 |
| SSLPORT=5900 |
| |
| In this case openssl(1) was used to create a PEM automatically. It |
| will prompt you if you want to protect it with with a passphrase. Use |
| "-ssl SAVE_NOPROMPT" to not be prompted. Use "-ssl TMP" to create a |
| temporary self-signed cert that will be discarded when x11vnc exits. |
| |
| Update: As of Nov/2008 x11vnc also supports the VeNCrypt SSL/TLS |
| tunnel extension to the VNC protocol. The older ANONTLS method (vino) |
| is also supported. This support is on by default when the -ssl option |
| is in use and can be fine-tuned using these options: -vencrypt, |
| -anontls, and -sslonly. |
| |
| The normal x11vnc -ssl operation is somewhat like a URL method |
| vncs://hostname if vnc://hostname indicates a standard unencrypted VNC |
| connection. Just as https://hostname is an SSL encrypted version of |
| http://hostname. The entire VNC session goes through the SSL tunnel. |
| VeNCrypt, on the other hand, switches to SSL/TLS early in the VNC |
| protocol handshake. x11vnc 0.9.6 supports both simultaneously when |
| -ssl is active. |
| |
| |
| SSL VNC Viewers:. Viewer-side will need to use SSL as well. See the |
| next FAQ and here for SSL enabled VNC Viewers, including SSVNC, to |
| connect to the above x11vnc via SSL. |
| |
| |
| As seen above, the PEM (privacy enhanced mail) file does not need to |
| be supplied if the openssl(1) command is available in PATH, in that |
| case a self-signed, certificate good the current and subsequent x11vnc |
| sessions is created (this may take a while on very slow machines.) |
| |
| In general, the PEM file contains both the Certificate (i.e. public |
| key) and the Private Key. Because of the latter, the file should be |
| protected from being read by untrusted users. The best way to do this |
| is to encrypt the key with a passphrase (note however this requires |
| supplying the passphrase each time x11vnc is started up.) |
| |
| See the discussion on x11vnc Key Management for some utilities |
| provided for creating and managing certificates and keys and even for |
| creating your own Certificate Authority (CA) for signing VNC server |
| and client certificates. This may be done by importing the certificate |
| into Web Browser or Java plugin keystores, or pointing stunnel to it. |
| The wrapper script ss_vncviewer provides an example on unix (see the |
| -verify option.) |
| |
| Here are some notes on the simpler default (non-CA) operation. To have |
| x11vnc save the generated certificate and key, use the "SAVE" keyword |
| like this: |
| x11vnc -ssl SAVE -display :0 ... |
| |
| (this is the same as the default: "-ssl".) This way it will be saved |
| in the default directory ~/.vnc/certs/ as server.crt (the certificate |
| only) and server.pem (both certificate and private key.) This opens up |
| the possibility of copying the server.crt to machines where the VNC |
| Viewer will be run to enable authenticating the x11vnc SSL VNC server |
| to the clients. When authentication takes place this way (or via the |
| more sophisticated CA signing described here), then |
| Man-In-The-Middle-Attacks are prevented. Otherwise, the SSL encryption |
| only provides protection against passive network traffic "sniffing" |
| (i.e. you are not protected against M-I-T-M attacks.) Nowadays, most |
| people seem mostly concerned mainly about passive sniffing (and the |
| default x11vnc SSL mode protects against it.) Note that there are |
| hacker tools like dsniff/webmitm and cain that implement SSL |
| Man-In-The-Middle attacks. They rely on the client not bothering to |
| check the cert. |
| |
| |
| One can test to some degree that SSL is working after starting x11vnc |
| with the -stunnel or -ssl option. From another machine one can use the |
| openssl command something like this: |
| openssl s_client -debug -msg -showcerts -connect far-away.east:5900 |
| |
| After all of the debugging output and informational messages you'll |
| see the string "RFB 003.008" that came from x11vnc. Pointing a web |
| browser connecting to: https://far-away.east:5900/ and then viewing |
| the SSL certificate information about the connection in the panels |
| will also work. |
| |
| Note: If you serve up the SSL enabled Java VNC Viewer via something |
| like: |
| x11vnc -ssl -httpdir /usr/local/share/x11vnc/classes/ssl |
| |
| (or just the -http option), you can test it out completely using that, |
| including using https to download it into the browser and connect to |
| x11vnc. |
| |
| |
| The older -stunnel option: Before the -ssl option there was a |
| convenience option -stunnel that would start an external SSL tunnel |
| for you using stunnel. The -ssl method is the preferred way, but for |
| historical reference we keep the -stunnel info here. |
| |
| The -stunnel mode requires the stunnel.mirt.net command stunnel(8) to |
| be installed on the system. |
| |
| Some -stunnel examples: |
| x11vnc -display :0 -stunnel /path/to/stunnel.pem -passwdfile ~/mypass |
| |
| x11vnc -display :0 -stunnel SAVE ... |
| |
| You'll get output like this: |
| The VNC desktop is: localhost:50 |
| The SSL VNC desktop is: far-away.east:0 |
| PORT=5950 |
| SSLPORT=5900 |
| |
| That indicates stunnel is listening on port 5900 for incoming |
| SSL-wrapped VNC connections from viewers. x11vnc is listening for |
| local connections on port 5950 in this case (remote viewers cannot |
| connect to it directly.) For -stunnel to work the stunnel command must |
| be installed on the machine and available in PATH (note stunnel is |
| often installed in sbin directories rather than bin.) Note that the |
| default "-stunnel" by itself creates a temporary cert (as in "-ssl |
| TMP".) |
| |
| |
| Q-54: How do I use VNC Viewers with built-in SSL tunneling? |
| |
| Notes on using "native" VNC Viewers with SSL: |
| |
| There aren't any native VNC Viewers that do SSL (ask your VNC viewer |
| developer to add the feature.) So a tunnel must be setup that you |
| point the VNC Viewer to. This is often STUNNEL. You can do this |
| manually, or use the ss_vncviewer script on Unix, or our Enhanced |
| TightVNC Viewer (SSVNC) package on Unix, Windows, or MacOSX. See the |
| next section for Java Web browser SSL VNC Viewers (you only need a |
| Java-enabled Web browser for it to work.) |
| |
| Notes on the SSL enabled Java VNC Viewer provided in x11vnc |
| classes/ssl/VncViewer.jar: |
| |
| A Java applet VNC Viewer allows you to connect to a VNC Server from a |
| Java-enabled Web browser. |
| |
| The SSL enabled Java VNC Viewer (VncViewer.jar) in the x11vnc package |
| supports only SSL based connections by default. As mentioned above the |
| -httpdir can be used to specify the path to .../classes/ssl. A typical |
| location might be /usr/local/share/x11vnc/classes/ssl. Or -http can be |
| used to try to have it find the directory automatically. |
| |
| Also note that the SingleClick UltraVNC Java Viewer is compatible with |
| x11vnc's -ssl SSL mode. (We tested it this way: "java -cp |
| ./VncViewer.jar VncViewer HOST far-away.east PORT 5900 USESSL 1 |
| TRUSTALL 1") |
| |
| The Java viewer uses SSL to communicate securely with x11vnc. Note |
| that the applet can optionally also be downloaded into your web |
| browser via HTTPS (which is HTTP over SSL.) This way the HTML page and |
| the Java applet itself are also delivered securely with SSL (as |
| opposed to only the VNC traffic being encrypted with SSL.) |
| |
| For this case the output will be something like this: |
| x11vnc -ssl SAVE -http |
| ... |
| The SSL VNC desktop is: far-away.east:0 |
| Java SSL viewer URL: https://far-away.east:5900/ |
| Java SSL viewer URL: http://far-away.east:5800/ |
| PORT=5900 |
| SSLPORT=5900 |
| |
| Indicating the two URLs (the first one encrypted, the second not) one |
| could point the web browser at to get the VNC viewer applet. E.g. put |
| this |
| http://far-away.east:5800/ |
| |
| or: |
| https://far-away.east:5900/ |
| |
| into your Java-enabled Web browser. |
| |
| Note that KDE's Konqueror web browser seems to have problems with |
| https Java applets, so you'll have to use the http/5800 with it (if |
| you get https/5900 working let us know how you did it.) |
| |
| If you are using a router/firewall with port-redirection, and you are |
| redirecting ports other than the default ones (5800, 5900) listed |
| above see here. |
| |
| The https service provided thru the actual VNC port (5900 in the above |
| example) can occasionally be slow or unreliable (it has to read some |
| input and try to guess if the connection is VNC or HTTP.) If it is |
| unreliable for you and you still want to serve the Java applet via |
| https, use the -https option to get an additional port dedicated to |
| https (its URL will also be printed in the output.) |
| |
| Another possibility is to add the GET applet parameter: |
| https://far-away.east:5900/?GET=1 |
| |
| This will have the VNC Viewer send a special HTTP GET string "GET |
| /request.https.vnc.connection HTTP/1.0" that x11vnc will notice more |
| quickly as a request for a VNC connection. Otherwise it must wait for |
| a timeout to expire before it assumes a VNC connection. |
| |
| You may also use "urlPrefix=somestring" to have /somestring prepended |
| to /request.https.vnc.connection". Perhaps you are using a web server |
| proxy scheme to enter a firewall or otherwise have rules applied to |
| the URL. If you need to have any slashes "/" in "somestring" use |
| "_2F_" (a deficiency in libvncserver prevents using the more natural |
| "%2F".) |
| |
| You apply multiple applet parameters in the regular URL way, e.g.: |
| https://far-away.east:5900/?GET=1&urlPrefix=mysubdir&... |
| |
| All of the x11vnc Java Viewer applet parameters are described in the |
| file classes/ssl/README |
| |
| |
| Tips on Getting the SSL Java Applet Working the First Time: |
| Unfortunately, it can be a little tricky getting the SSL VNC Java |
| Viewer working with x11vnc. Here are some tips to getting working the |
| first time (afterwards you can incrementally customize with more |
| complex settings.) |
| * First try it on the LAN: Do NOT try to have it work the first time |
| going through firewalls, Web proxies, home router port |
| redirections, or Apache portal. Just try a direct connection over |
| your LAN first (if you only have 1 machine and no LAN, just do a |
| direct connection to the same machine: localhost.) If the LAN |
| machine you run x11vnc on has its own host-level firewall (most |
| linux machine come with that on by default), disable it or at |
| least let tcp ports 5800-6000 through. |
| * First try HTTP to download the Java Applet: x11vnc can serve both |
| the Java Applet jar file and VNC out of the same port (both |
| tunneled through SSL, see below.) But it can lead to timing and |
| other problems. So first try HTTP instead of HTTPS to download the |
| Applet jar file (VncViewer.jar.) That is to say try |
| http://hostname:5800 in your web browser first before trying |
| https://hostname:5900. x11vnc will print out the ports and URLs it |
| is using, so use the HTTP one it prints out. |
| * Always Restart the Browser: If you are having failures and have to |
| repeatedly retry things ALWAYS restart the browser (i.e. |
| completely exit it and then start a new browser process) each |
| time. Otherwise as you are changing things the browser may |
| "remember" failed applet downloads, etc. and just add to the |
| confusion and irreproducibility. If you see it trying to download |
| VncViewer.class (instead of VncViewer.jar) you know it is really |
| confused and needs to be restarted. |
| * Step Lively: If you get Browser or Java VM or VNC Viewer applet |
| dialog boxes saying things like "Do you want to trust this |
| certificate?" or "The hostname does not match the one on the |
| certificate", etc. just go through them as quickly as possible. |
| x11vnc cannot wait forever for each SSL connection, and so if you |
| dawdle too long inspecting the certs, etc it can lead to problems. |
| Get it working first before taking your time to read the details |
| in the dialogs, etc. |
| * No inetd, Please: Even if you intend to deploy via inetd or xinetd |
| eventually, get that working later (and remember do not use |
| something like "-ssl TMP" that creates a new temporary SSL |
| certificate for every new socket connection.) |
| * Nothing Fancy: Do not try fancy stuff like -svc, -create, -unixpw, |
| "-users unixpw=", "-users sslpeer=", -sslverify, etc. Just get the |
| simplest connection working first and then incrementally add what |
| you need. |
| |
| So the recommended test command lines are: |
| x11vnc -ssl SAVE -http |
| x11vnc -ssl SAVE -httpdir /path/to/x11vnc/classes/ssl |
| |
| Use the latter if x11vnc cannot automatically find the classes/ssl |
| directory (this what the -http option instructs it to do.) Then point |
| your browser to the HTTP (not HTTPS) URL it prints out. |
| |
| Following the above guidelines, did it work? If so, Congratulations!! |
| you created an SSL encrypted connection between the SSL Java applet |
| running in your web browser and x11vnc. The fact that you used HTTP |
| instead of HTTPS to download the applet is not the end of the world |
| (some users do it this way), the main thing is that the VNC traffic is |
| encrypted with SSL. If you are having trouble even with the above |
| baseline test case feel free to contact me (please send the Full |
| x11vnc output, not just part of it; the complete x11vnc command line; |
| the URL(s) entered in the browser; the full Java Console output; and |
| anything else you can think of.) |
| |
| Next, you can add the features you want one by one testing it still |
| works each time. I suggest first turning on the HTTPS applet download |
| (https://hostname:5900) if that is what you intend to use. That one |
| gives the most trouble because of the ambiguity of passing two |
| different protocols (HTTP and VNC) through the same SSL service port. |
| |
| Next, turn on inetd if you intend to use that (this can be tricky too, |
| be sure to use -oa logfile and inspect it carefully if there are |
| problems.) If you are going to use non-standard ports (e.g. "-rfbport |
| 443" as root), work on that next. Then enable the firewall, router |
| port redirection channel (you will somehow need to be outside to do |
| that, maybe test that through another VNC session.) |
| |
| Then, if you plan to use them, enable "fancy stuff" like "-svc" or |
| "-unixpw", etc, etc. Be sure to add a password either "-rfbauth" or |
| "-unixpw" or both. If you need to have the web browser use a corporate |
| Web Proxy (i.e. it cannot connect directly) work on that last. Ditto |
| for the Apache portal. |
| |
| |
| Router/Firewall port redirs: If you are doing port redirection at |
| your router to an internal machine running x11vnc AND the internet |
| facing port is different from the internal machine's VNC port, you |
| will need to apply the PORT applet parameter to indicate to the applet |
| the Internet facing port number (otherwise by default the internal |
| machine's port, say 5900, is sent and that of course is rejected at |
| the firewall/router.) For example: |
| https://far-away.east:443/?GET=1&PORT=443 |
| |
| So in this example the user configures his router to redirect |
| connections to port 443 on his Internet side to, say, port 5900 on the |
| internal machine running x11vnc. See also the -httpsredir option that |
| will try to automate this for you. |
| |
| To configure your router to do port redirection, see its instructions. |
| Typically, from the inside you point a web browser to a special URL |
| (e.g. http://192.168.1.1) and you get a web interface to configure it. |
| Look for something like "Port Redirection" or "Port Forwarding", |
| probably under "Advanced" or something like that. If you have a Linux |
| or Unix system acting as your firewall/router, see its firewall |
| configuration. |
| |
| You can also use x11vnc options -rfbport NNNNN and -httpport NNNNN to |
| match the ports that your firewall will be redirecting to the machine |
| where x11vnc is run. |
| |
| |
| Tedious Dialogs: If you do serve the SSL enabled Java viewer via https |
| be prepared for quite a number of "are you sure you trust this site?" |
| dialogs: |
| * First from the Web browser that cannot verify the self-signed |
| certificate when it downloads index.vnc. |
| * From the Web browser again noting that the common name on the |
| certificate does not match the hostname of the remote machine. |
| * Next from the Java VM that cannot verify the self-signed |
| certificate when it downloads VncViewer.jar. |
| * And also from the Java VM again noting that the common name on the |
| certificate does not match the hostname of the remote machine. |
| * Finally from the Java VncViewer applet itself saying it cannot |
| verify the certificate! (or a popup asking you if you want to see |
| the certificate.) |
| |
| Note that sometimes if you pause too long at one of the above dialogs |
| then x11vnc may exceed a timeout and assume the current socket |
| connection is VNC instead of the HTTPS it actually is (but since you |
| have paused too long at the dialog the GET request comes too late.) |
| Often hitting Reload and going through the dialogs more quickly will |
| let you connect. The Java VM dialogs are the most important ones to |
| NOT linger at. If you see in the x11vnc output a request for |
| VncViewer.class instead of VncViewer.jar it is too late... you will |
| need to completely restart the Web browser to get it to try for the |
| jar again. You can use the -https option if you want a dedicated port |
| for HTTPS connections instead of sharing the VNC port. |
| |
| To see example x11vnc output for a successful https://host:5900/ |
| connection with the Java Applet see This Page. And here is a newer |
| example including the Java Console output. |
| |
| All of the x11vnc Java Viewer applet parameters are described in the |
| file classes/ssl/README |
| |
| |
| Notes on the VNC Viewer ss_vncviewer wrapper script: |
| |
| If you want to use a native VNC Viewer with the SSL enabled x11vnc you |
| will need to run an external SSL tunnel on the Viewer side. There do |
| not seem to be any native SSL VNC Viewers outside of our x11vnc and |
| SSVNC packages. The basic ideas of doing this were discussed for |
| external tunnel utilities here. |
| |
| The ss_vncviewer script provided with x11vnc and SSVNC can set up the |
| stunnel tunnel automatically on unix as long as the stunnel command is |
| installed on the Viewer machine and available in PATH (and vncviewer |
| too of course.) Note that on a Debian based system you will need to |
| install the package stunnel4 not stunnel. You can set the environment |
| variables STUNNEL and VNCVIEWERCMD to point to the correct programs if |
| you want to override the defaults. |
| |
| Here are some examples: |
| 1) ss_vncviewer far-away.east:0 |
| |
| 2) ss_vncviewer far-away.east:0 -encodings "copyrect tight zrle hextile" |
| |
| 3) ss_vncviewer -verify ./server.crt far-away.east:0 |
| |
| 4) ss_vncviewer -mycert ./client.pem far-away.east:0 |
| |
| 5) ss_vncviewer -proxy far-away.east:8080 myworkstation:0 |
| |
| The first one is the default mode and accepts the x11vnc certificate |
| without question. The second one is as the first, but adds the |
| -encodings options to the vncviewer command line. |
| |
| The third one requires that the x11vnc server authenticate itself to |
| the client against the certificate in the file ./server.crt (e.g. one |
| created by "x11vnc -ssl SAVE" and safely copied to the VNC viewer |
| machine.) |
| |
| The fourth one is for VNC Viewer authentication, it uses ./client.pem |
| to authenticate itself to x11vnc. One can supply both -verify and |
| -mycert simultaneously. |
| |
| The fifth one shows that Web proxies can be used if that is the only |
| way to get out of the firewall. If the "double proxy" situation arises |
| separate the two by commas. See this page for more information on how |
| Web proxies come into play. |
| |
| If one uses a Certificate Authority (CA) scheme described here, the |
| wrapper script would use the CA cert instead of the server cert: |
| 3') ss_vncviewer -verify ./cacert.crt far-away.east:0 |
| |
| Update Jul/2006: we now provide an Enhanced TightVNC Viewer (SSVNC) |
| package that starts up STUNNEL automatically along with some other |
| features. All binaries (stunnel, vncviewer, and some utilities) are |
| provided in the package. It works on Unix, Mac OS X, and Windows. |
| |
| |
| Q-55: How do I use the Java applet VNC Viewer with built-in SSL |
| tunneling when going through a Web Proxy? |
| The SSL enabled Java VNC Viewer and firewall Proxies: |
| |
| SSL and HTTPS aside, there is a general problem with Firewall Proxies |
| and Java Applets that open sockets. The applet is downloaded |
| successfully (through the browser) using HTTP and the proxy, but when |
| the applet tries to reconnect to the originating host (the only one |
| allowed by security) it does not use the proxy channel. So it cannot |
| reconnect to the server the applet came from! |
| |
| We have found a convenient workaround: in the directory where |
| VncViewer.jar resides there is a digitally signed version of the same |
| applet called SignedVncViewer.jar. Since the applet is digitally |
| signed, there will be an additional dialog from the Java VM plugin |
| asking you if you want to trust the applet fully. |
| |
| You should say "Yes". If you do, the applet will be run in a mode |
| where it can try to determine the firewall proxy host name and port |
| (it will ask you for them if it cannot find them.) This way it can |
| connect directly to the Proxy and then request the CONNECT method to |
| be redirected to the originating host (the x11vnc VNC Server.) SSL is |
| then layered over this socket. |
| |
| To do this you should use the proxy.vnc HTML file like via this URL in |
| your browser: |
| https://yourmachine.com:5900/proxy.vnc |
| |
| (instead of the unsigned one in https://yourmachine.com:5900/ that |
| gives the default index.vnc) |
| |
| Proxies that limit CONNECT to ports 443 and 563: |
| |
| Things become trickier if the Web proxy restricts which CONNECT ports |
| can be redirected to. For security, some (most?) proxies only allow |
| port 443 (HTTPS) and 563 (SNEWS) by default. In this case, the only |
| thing to do is run x11vnc on that low port, e.g. "-rfbport 443", (or |
| use a port redirection on, say, a firewall or router port 443 to the |
| internal machine.) |
| |
| If you do such a redirection to an internal machine and x11vnc is not |
| listening on port 443, you will probably need to edit proxy.vnc. |
| Suppose the SSL x11vnc server was listening on port 5901. You should |
| change the line in proxy.vnc from: |
| <param name=PORT value=$PORT> |
| |
| to: |
| <param name=PORT value=443> |
| |
| Since otherwise $PORT will be expanded to 5901 by x11vnc and the |
| viewer applet will fail to connect to that port on the firewall. |
| |
| Another way to achieve the same thing is to use the applet PORT |
| parameter: |
| https://yourmachine.com/proxy.vnc?PORT=443 |
| |
| this is cleaner because it avoids editing the file, but requires more |
| parameters in the URL. See also the -httpsredir x11vnc option that |
| will try to automate this for you. To use the GET trick discussed |
| above, do: |
| https://yourmachine.com/proxy.vnc?GET=1&PORT=443 |
| |
| All of the x11vnc Java Viewer applet parameters are described in the |
| file classes/ssl/README |
| |
| Here is an example of Java Console and x11vnc output for the Web proxy |
| case. |
| |
| |
| Note that both the ss_vncviewer stunnel Unix wrapper script and |
| Enhanced TightVNC Viewer (SSVNC) can use Web proxies as well even |
| though they do not involve a Web browser. |
| |
| |
| Q-56: Can Apache web server act as a gateway for users to connect via |
| SSL from the Internet with a Web browser to x11vnc running on their |
| workstations behind a firewall? |
| Yes. You will need to configure apache to forward these connections. |
| It is discussed here. This SSL VNC portal provides a clean alternative |
| to the traditional method where the user uses SSH to log in through |
| the gateway to create the encrypted port redirection to x11vnc running |
| on her desktop. |
| |
| Also see the desktop.cgi CGI script method that achieves much of what |
| this Apache VNC SSL portal method does (as long as desktop.cgi's 'port |
| redirection' mode is enabled.) |
| |
| |
| Q-57: Can I create and use my own SSL Certificate Authority (CA) with |
| x11vnc? |
| Yes, see this page for how to do this and the utility commands x11vnc |
| provides to create and manage many types of certificates and private |
| keys. |
| |
| |
| |
| [Display Managers and Services] |
| |
| Q-58: How can I run x11vnc as a "service" that is always available? |
| |
| There are a number of ways to do this. The primary thing you need to |
| decide is whether you want x11vnc to connect to the X session on the |
| machine 1) regardless of who (or if anyone) has the X session, or 2) |
| only if a certain user has the X session. Because X sessions are |
| protected by X permissions (MIT-MAGIC-COOKIE files XAUTHORITY and |
| $HOME/.Xauthority) the automatically started x11vnc will of course |
| need to have sufficient permissions to connect to the X display. |
| |
| Here are some ideas: |
| * Use the description under "Continuously" in the FAQ on x11vnc and |
| Display Managers |
| * Use the description in the FAQ on x11vnc and inetd(8) |
| * Use the description in the FAQ on Unix user logins and inetd(8) |
| * Start x11vnc from your $HOME/.xsession (or $HOME/.xinitrc or |
| autostart script or ...) |
| * Although less reliable, see the x11vnc_loop rc.local hack below. |
| |
| The display manager scheme will not be specific to which user has the |
| X session unless a test is specifically put into the display startup |
| script (often named Xsetup.) The inetd(8) scheme may or may not be |
| specific to which user has the X session (and it may not be able to do |
| all users via the XAUTHORITY permission issues.) |
| |
| The .xsession/.xinitrc scheme is obviously is specific to a particular |
| user and only when they are logged into X. If you do not know what a |
| $HOME/.xsession script is or how to use one, perhaps your desktop has |
| a "session startup commands" configuration option. The command to be |
| run in the .xsession or .xinitrc file may look like this: |
| x11vnc -logfile $HOME/.x11vnc.log -rfbauth $HOME/.vnc/passwd -forever -bg |
| |
| plus any other options you desire. |
| |
| Depending on your desktop and/or OS/distribution the automatically run |
| X startup scripts (traditionally .xsession/.xinitrc) may have to be in |
| a different directory or have a different basename. One user |
| recommends the description under 'Running Scripts Automatically' at |
| this link. |
| |
| Firewalls: note all methods will require the host-level firewall to be |
| configured to allow connections in on a port. E.g. 5900 (default VNC |
| port) or 22 (default SSH port for tunnelling VNC.) Most systems these |
| days have firewalls turned on by default, so you will actively have to |
| do something to poke a hole in the firewall at the desired port |
| number. See your system administration tool for Firewall settings |
| (Yast, Firestarter, etc.) |
| |
| |
| Q-59: How can I use x11vnc to connect to an X login screen like xdm, |
| GNOME gdm, KDE kdm, or CDE dtlogin? (i.e. nobody is logged into an X |
| session yet.) |
| |
| We describe two scenarios here. The first is called 'One time only' |
| meaning you just need to do it quickly once and don't want to repeat; |
| and the second is called 'Continuously' meaning you want the access to |
| be available after every reboot and after every desktop logout. |
| _________________________________________________________________ |
| |
| One time only: If the X login screen is running and you just want to |
| connect to it once (i.e. a one-shot): |
| |
| It is usually possible to do this by just adjusting the XAUTHORITY |
| environment variable to point to the correct MIT-COOKIE auth file |
| while running x11vnc as root, e.g. for the gnome display manager, GDM: |
| x11vnc -auth /var/gdm/:0.Xauth -display :0 |
| |
| (the -auth option sets the XAUTHORITY variable for you.) |
| |
| There will be a similar thing to do for xdm using however a different |
| auth directory path (perhaps something like |
| /var/lib/xdm/authdir/authfiles/A:0-XQvaJk) for the xdm greeter or |
| /var/lib/kdm/A:0-crWk72 (or /var/run/xauth/A:0-qQPftr, etc. etc) for |
| the kdm greeter. Of course, the random characters in the file basename |
| will vary and you will need to use the actual filename on your system. |
| Read your system docs to find out where the display manager cookie |
| files are kept. |
| |
| Trick: sometimes ps(1) can reveal the X server process -auth argument |
| (e.g. "ps wwaux | grep auth") and hence the path to the auth file. |
| |
| x11vnc must be run as root for this because the /var/gdm/:0.Xauth, |
| /var/lib/kdm/A:0-crWk72, etc. auth files are only readable by root. If |
| you do not want to run x11vnc as root, you can copy (as root or sudo) |
| the auth file to some location and make it readable by your userid. |
| Then run x11vnc as your userid with -auth pointed to the copied file. |
| |
| Update Dec/2009: use "-auth guess" to have x11vnc try to guess the |
| location of the auth file for you. |
| |
| You next connect to x11vnc with a VNC viewer, give your username and |
| password to the X login prompt to start your session. |
| |
| Note: GDM: gdm seems to have an annoying setting that causes x11vnc |
| (and any other X clients) to be killed after the user logs in. Setting |
| KillInitClients=false in the [daemon] section of /etc/X11/gdm/gdm.conf |
| (or /etc/gdm/gdm.conf, etc.) avoids this. Otherwise, just restart |
| x11vnc and then reconnect your viewer. Other display managers (kdm, |
| etc) may also have a similar problem. One user reports having to alter |
| "gdm.conf-custom" as well. |
| |
| Note: Solaris: For dtlogin in addition to the above sort of trick |
| (BTW, the auth file should be in /var/dt), you'll also need to add |
| something like Dtlogin*grabServer:False to the Xconfig file |
| (/etc/dt/config/Xconfig or /usr/dt/config/Xconfig on Solaris, see the |
| example at the end of this FAQ.) Then restart dtlogin, e.g.: |
| /etc/init.d/dtlogin stop; /etc/init.d/dtlogin start or reboot. |
| |
| Update Nov/2008: Regarding GDM KillInitClients: see the -reopen option |
| for another possible workaround. |
| |
| Update Oct/2009: Regarding GDM KillInitClients: starting with x11vnc |
| 0.9.9 it will try to apply heuristics to detect if a window manager is |
| not running (i.e. whether the Display Manager Greeter Login panel is |
| still up.) If it thinks the display manager login is still up it will |
| delay creating windows or using XFIXES. The former is what GDM uses to |
| kill the initial clients, use of the latter can cause a different |
| problem: an Xorg server crash. So with 0.9.9 and later it should all |
| work without needing to set KillInitClients=false (which is a good |
| because recent GDM, v2.24, has removed this option) or use -noxfixes. |
| To disable the heuristics and delaying set X11VNC_AVOID_WINDOWS=never; |
| to set the delay time explicitly use, e.g., X11VNC_AVOID_WINDOWS=120 |
| (delays for 120 seconds after the VNC connection; you have that long |
| to log in.) |
| _________________________________________________________________ |
| |
| Continuously: Have x11vnc reattach each time the X server is |
| restarted (i.e. after each logout and reboot): |
| |
| To make x11vnc always attached to the X server including the login |
| screen you will need to add a command to a display manager startup |
| script. |
| |
| Please consider the security implications of this! The VNC display for |
| the X session always accessible (but hopefully password protected.) |
| Add -localhost if you only plan to access via a SSH tunnel. |
| |
| The name of the display manager startup script file depends on desktop |
| used and seem to be: |
| GDM (GNOME) /etc/X11/gdm/Init/Default |
| /etc/gdm/Init/Default |
| KDM (KDE) /etc/kde*/kdm/Xsetup |
| XDM /etc/X11/xdm/Xsetup (or sometimes xdm/Xsetup_0) |
| CDE /etc/dt/config/Xsetup |
| |
| although the exact location can be operating system, distribution, and |
| time dependent. See the documentation for your display manager: |
| gdm(1), kdm(1), xdm(1), dtlogin(1) for additional details. There may |
| also be display number specific scripts: e.g. Xsetup_0 vs. Xsetup, you |
| need to watch out for. |
| |
| Note: You should read and understand all of the Note's and Update's |
| in the 'One time only' section above. All of the GDM topics apply here |
| as well: |
| |
| Note: GDM: The above (in 'One time only') gdm setting of |
| KillInitClients=false in /etc/X11/gdm/gdm.conf (or /etc/gdm/gdm.conf, |
| etc.) for GDM is needed here as well. Other display managers (KDM, |
| etc) may also have a similar problem. |
| |
| Also see the Update Oct/2009 above where x11vnc 0.9.9 and later |
| automatically avoids being killed. |
| |
| Note: DtLogin: The above (in 'One time only') |
| Dtlogin*grabServer:False step for Solaris will be needed for dtlogin |
| here as well. |
| |
| In any event, the line you will add to the display manager script |
| (Xsetup, Default, or whatever) will look something like: |
| /usr/local/bin/x11vnc -rfbauth /path/to/the/vnc/passwd -o /var/log/x11vnc.log |
| -forever -bg |
| |
| where you should customize the exact command to your needs (e.g. |
| -localhost for SSH tunnel-only access; -ssl SAVE for SSL access; etc.) |
| |
| Happy, happy, joy, joy: Note that we do not need to specify -display |
| or -auth because happily they are already set for us in the DISPLAY |
| and XAUTHORITY environment variables for the Xsetup script!!! |
| |
| You may also want to force the VNC port with something like "-rfbport |
| 5900" (or -N) to avoid autoselecting one if 5900 is already taken. |
| _________________________________________________________________ |
| |
| Fedora/gdm: Here is an example of what we did on a vanilla install of |
| Fedora-C3 (seems to use gdm by default.) Add a line like this to |
| /etc/X11/gdm/Init/:0 |
| /usr/local/bin/x11vnc -rfbauth /etc/x11vnc.passwd -forever -bg -o /var/log/x1 |
| 1vnc.log |
| |
| And then add this line to /etc/X11/gdm/gdm.conf (or /etc/gdm/gdm.conf, |
| etc.) in the [daemon] section: |
| KillInitClients=false |
| |
| Then restart: /usr/sbin/gdm-restart (or reboot.) The |
| KillInitClients=false setting is important: without it x11vnc will be |
| killed immediately after the user logs in. Here are full details on |
| how to configure gdm |
| _________________________________________________________________ |
| |
| Solaris/dtlogin: Here is an example of what we did on a vanilla |
| install of Solaris: |
| Make the directory /etc/dt/config: |
| mkdir -p /etc/dt/config |
| |
| Copy over the Xconfig file for customization: |
| cp /usr/dt/config/Xconfig /etc/dt/config/Xconfig |
| |
| Edit /etc/dt/config/Xconfig and uncomment the line: |
| Dtlogin*grabServer: False |
| |
| Next, copy over Xsetup for customization: |
| cp /usr/dt/config/Xsetup /etc/dt/config/Xsetup |
| |
| Edit /etc/dt/config/Xsetup and at the bottom put a line like: |
| /usr/local/bin/x11vnc -forever -o /var/log/x11vnc.log -bg |
| |
| (tweaked to your local setup and preferences, a password via -rfbauth, |
| etc. would be a very good idea.) |
| |
| Restart the X server and dtlogin: |
| /etc/init.d/dtlogin stop |
| /etc/init.d/dtlogin start |
| |
| (or reboot or maybe just restart the X session.) |
| _________________________________________________________________ |
| |
| KDM: One user running the kdm display manager reports putting this |
| line: |
| x11vnc -forever -rfbauth /home/xyz/.vnc/passwd -bg -o /var/log/x11vnc.log |
| |
| in /etc/kde/kdm/Xsetup. After rebooting the system it all seemed to |
| work fine. |
| _________________________________________________________________ |
| |
| |
| If you do not want to deal with any display manager startup scripts, |
| here is a kludgey script that can be run manually or out of a boot |
| file like rc.local: x11vnc_loop It will need some local customization |
| before running. Because the XAUTHORITY auth file must be guessed by |
| this script, use of the display manager script method described above |
| is greatly preferred. There is also the -loop option that does |
| something similar. |
| |
| If the machine is a traditional Xterminal you may want to read this |
| FAQ. |
| |
| Firewalls: note all methods will require the host-level firewall to be |
| configured to allow connections in on a port. E.g. 5900 (default VNC |
| port) or 22 (default SSH port for tunnelling VNC.) Most systems these |
| days have firewalls turned on by default, so you will actively have to |
| do something to poke a hole in the firewall at the desired port |
| number. See your system administration tool for Firewall settings |
| (Yast, Firestarter, etc.) |
| |
| |
| Q-60: Can I run x11vnc out of inetd(8)? How about xinetd(8)? |
| |
| Yes, perhaps a line something like this in /etc/inetd.conf will do it |
| for you: |
| |
| 5900 stream tcp nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc_sh |
| |
| where the shell script /usr/local/bin/x11vnc_sh uses the -inetd option |
| and looks something like (you'll need to customize to your settings.) |
| #!/bin/sh |
| /usr/local/bin/x11vnc -inetd -display :0 -auth /home/fred/.Xauthority \ |
| -rfbauth /home/fred/.vnc/passwd -o /var/log/x11vnc_sh.log |
| |
| Important: Note that you must redirect the standard error output to a |
| log file (e.g. -o logfile) or "2>/dev/null" for proper operation via |
| inetd (otherwise the standard error also goes to the VNC vncviewer, |
| and that confuses it greatly, causing it to abort.) If you do not use |
| a wrapper script as above but rather call x11vnc directly in |
| /etc/inetd.conf and do not redirect stderr to a file, then you must |
| specify the -q (aka -quiet) option: "/usr/local/bin/x11vnc -q -inetd |
| ...". When you supply both -q and -inet and no "-o logfile" then |
| stderr will automatically be closed (to prevent, e.g. library stderr |
| messages leaking out to the viewer.) The recommended practice is to |
| use "-o logfile" to collect the output in a file or wrapper script |
| with "2>logfile" redirection because the errors and warnings printed |
| out are very useful in troubleshooting problems. |
| |
| Note also the need to set XAUTHORITY via -auth to point to the |
| MIT-COOKIE auth file to get permission to connect to the X display |
| (setting and exporting the XAUTHORITY variable accomplishes the same |
| thing.) See the x11vnc_loop file in the previous question for more |
| ideas on what that auth file may be, etc. The scheme described in the |
| FAQ on Unix user logins and inetd(8) works around the XAUTHORITY issue |
| nicely. |
| |
| Note: On Solaris you cannot have the bare number 5900 in |
| /etc/inetd.conf, you'll need to replace it with a word like x11vnc an |
| then put something like "x11vnc 5900/tcp" in /etc/services. |
| |
| Since the process runs as root, it might be a bad idea to have the |
| logfile in a world-writable area like /tmp if there are untrustworthy |
| users on the machine. Perhaps /var/log is a better place. |
| |
| Be sure to look at your /etc/hosts.allow and /etc/hosts.deny settings |
| to limit the machines that can connect to this service (your desktop!) |
| For the above example with /etc/hosts.allow: |
| x11vnc_sh : 123.45.67.89 |
| |
| A really safe way to do things is to limit the above inetd to |
| localhost only (via /etc/hosts.allow) and use ssh to tunnel the |
| incoming connection. Using inetd for this prevents there being a tiny |
| window of opportunity between x11vnc starting up and your vncviewer |
| connecting to it. Always use a VNC password to further protect against |
| unwanted access. |
| |
| For xinetd(8), one user reports he created the file |
| /etc/xinetd.d/x11vncservice containing the following: |
| # default: off |
| # description: |
| service x11vncservice |
| { |
| flags = REUSE NAMEINARGS |
| port = 5900 |
| type = UNLISTED |
| socket_type = stream |
| protocol = tcp |
| wait = no |
| user = root |
| server = /usr/sbin/tcpd |
| server_args = /usr/local/bin/x11vnc_sh |
| disable = no |
| } |
| |
| With the contents of /usr/local/bin/x11vnc_sh similar to the example |
| given above. One user reports this works with avoiding the wrapper |
| script: |
| service x11vncservice |
| { |
| port = 5900 |
| type = UNLISTED |
| socket_type = stream |
| protocol = tcp |
| wait = no |
| user = root |
| server = /usr/local/bin/x11vnc |
| server_args = -inetd -q -display :0 -auth /var/gdm/:0.Xauth |
| disable = no |
| } |
| |
| (or one can replace the -q with say "-o /var/log/x11vnc.log" to |
| capture a log) |
| |
| The above works nicely for GDM because the -auth file is a fixed name. |
| For KDM or XDM the filename varies. Here is one idea for a x11vnc_sh |
| wrapper to try to guess the name: |
| #!/bin/sh |
| COLUMNS=256 |
| export COLUMNS |
| authfile=`ps wwaux | grep '/X.*-auth' | grep -v grep | sed -e 's/^.*-auth *//' |
| -e 's/ .*$//' | head -n 1` |
| |
| if [ -r "$authfile" ]; then |
| exec /usr/local/bin/x11vnc -inetd -o /var/log/x11vnc.log -display :0 -a |
| uth "$authfile" |
| fi |
| exit 1 |
| |
| Starting with x11vnc 0.9.3 this can be automated by: |
| #!/bin/sh |
| exec /usr/local/bin/x11vnc -inetd -o /var/log/x11vnc.log -find -env FD_XDM=1 |
| |
| |
| Q-61: Can I have x11vnc advertise its VNC service and port via mDNS / |
| Zeroconf (e.g. Avahi) so VNC viewers on the local network can detect |
| it automatically? |
| |
| Yes, as of Feb/2007 x11vnc supports mDNS / Zeroconf advertising of its |
| service via the Avahi client library. Use the option -avahi (same as |
| -mdns or -zeroconf) to enable it. Depending on your setup you may need |
| to install Avahi (including the development/build packages), enable |
| the server: avahi-daemon and avahi-dnsconfd, and possibly open up UDP |
| port 5353 on your firewall. |
| |
| If the Avahi client library or build environment is not available at |
| build-time, then at run-time x11vnc will try to look for external |
| helper programs, avahi-browse(1) or dns-sd(1), to do the work. |
| |
| The service was tested with Chicken of the VNC ("Use Bonjour" |
| selected) on a Mac on the same network and the service was noted and |
| listed in the servers list. Clicking on it and then "Connect" |
| connected automatically w/o having to enter any hostnames or port |
| numbers. |
| |
| It appears SuSE 10.1 comes with avahi (or you can add packages, e.g. |
| avahi-0.6.5-27) but not the development package (you can use the |
| OpenSuSE avahi-devel rpm.) Unfortunately, you may need to disable |
| another Zeroconf daemon "/etc/init.d/mdnsd stop", before doing |
| "/etc/init.d/avahi-daemon start" and "/etc/init.d/avahi-dnsconfd |
| start". We also had to comment out the browse-domains line in |
| /etc/avahi/avahi-daemon.conf. Hopefully there is "LessConf" to do on |
| other distros/OS's... |
| |
| |
| Q-62: Can I have x11vnc allow a user to log in with her UNIX username |
| and password and then have it find her X session display on that |
| machine and then attach to it? How about starting an X session if one |
| cannot be found? |
| |
| The easiest way to do this is via inetd(8) using the -unixpw and |
| -display WAIT options. The reason inetd(8) makes this easier is that |
| it starts a new x11vnc process for each new user connection. Otherwise |
| a wrapper would have to listen for connections and spawn new x11vnc's |
| (see this example and also the -loopbg option.) inetd(8) is not |
| required for this, but it makes some aspects more general. |
| |
| Also with inetd(8) users always connect to a fixed VNC display, say |
| hostname:0, and do not need to memorize a special VNC display number |
| just for their personal use, etc. |
| |
| Update: Use the -find, -create, -svc, and -xdmsvc options that are |
| shorthand for common FINDCREATEDISPLAY usage modes (e.g. terminal |
| services) described below. (i.e. simply use "-svc" instead of the |
| cumbersome "-display WAIT:cmd=FINDCREATEDISPLAY-Xvfb -unixpw -users |
| unixpw= -ssl SAVE") |
| |
| The -display WAIT option makes x11vnc wait until a VNC viewer is |
| connected before attaching to the X display. |
| |
| Additionally it can be used to run an external command that returns |
| the DISPLAY and XAUTHORITY data. We provide some useful builtin ones |
| (FINDDISPLAY and FINDCREATEDISPLAY below), but in principle one could |
| supply his own script: "-display WAIT:cmd=/path/to/find_display" where |
| the script find_display might look something like this. |
| |
| A default script somewhat like the above is used under "-display |
| WAIT:cmd=FINDDISPLAY" (same as -find) The format for any such command |
| is that it returns DISPLAY=:disp as the first line and any remaining |
| lines are either XAUTHORITY=file or raw xauth data (the above example |
| does the latter.) If applicable (-unixpw mode), the program is run as |
| the Unix user name who logged in. |
| |
| On Linux if the virtual terminal is known the program appends ",VT=n" |
| to the DISPLAY line; a chvt n will be attempted automatically. Or if |
| only the X server process ID is known it appends ",XPID=n" (a chvt |
| will be attempted by x11vnc.) |
| |
| Tip: Note that the -find option is an alias for "-display |
| WAIT:cmd=FINDDISPLAY". Use it! |
| |
| The -unixpw option allows UNIX password logins. It conveniently knows |
| the Unix username whose X display should be found. Here are a couple |
| /etc/inetd.conf examples of this usage: |
| 5900 stream tcp nowait nobody /usr/sbin/tcpd /usr/local/bin/x11vnc -inetd |
| -unixpw \ |
| -find -o /var/log/x11vnc.log -ssl SAVE -ssldir /usr/local/certs |
| 5900 stream tcp nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc -inetd |
| -unixpw \ |
| -find -o /var/log/x11vnc.log -ssl SAVE -users unixpw= |
| |
| Note we have used the -find alias and the very long lines have been |
| split. An alternative is to use a wrapper script, e.g. |
| /usr/local/bin/x11vnc.sh that has all of the options. (see also the |
| -svc alias.) |
| |
| In the first inetd line x11vnc is run as user "nobody" and stays user |
| nobody during the whole session. The permissions of the log files and |
| certs directory will need to be set up to allow "nobody" to use them. |
| |
| In the second one x11vnc is run as root and switches to the user that |
| logs in due to the "-users unixpw=" option. |
| |
| Note that SSL is required for this mode because otherwise the Unix |
| password would be passed in clear text over the network. In general |
| -unixpw is not required for this sort of scheme, but it is convenient |
| because it determines exactly who the Unix user is whose display |
| should be sought. Otherwise the find_display script would have to use |
| some method to work out DISPLAY, XAUTHORITY, etc (perhaps you use |
| multiple inetd ports and hardwire usernames for different ports.) |
| |
| If you really want to disable the SSL or SSH -localhost constraints |
| (this is not recommended unless you really know what you are doing: |
| Unix passwords sent in clear text is a very bad idea...) read the |
| -unixpw documentation. |
| |
| A inetd(8) scheme for a fixed user that doesn't use SSL or unix |
| passwds could be: |
| /usr/local/bin/x11vnc -inetd -users =fred -find -rfbauth /home/fred/.vnc/pass |
| wd -o /var/log/x11vnc.log |
| |
| The "-users =fred" option will cause x11vnc to switch to user fred and |
| then find his X display. The VNC password (-rfbauth) as opposed to |
| Unix password (-unixpw) is used to authenticate the VNC client. |
| |
| Similar looking commands to the above examples can be run directly and |
| do not use inetd (just remove the -inetd option and run from the |
| cmdline, etc.) |
| |
| |
| X Session Creation: An added (Nov/2006) extension to FINDDISPLAY is |
| FINDCREATEDISPLAY where if it does not find an X display via the |
| FINDDISPLAY method it will create an X server session for the user |
| (i.e. desktop/terminal server.) This is the only time x11vnc actually |
| tries to start up an X server (normally it just attaches to an |
| existing one.) |
| |
| For virtual sessions you will need to install the Xvfb program (e.g. |
| apt-get install xvfb) or our Xdummy program (see below.) |
| |
| By default it will only try to start up virtual (non-hardware) X |
| servers: first Xvfb and if that is not available then Xdummy (included |
| in the x11vnc source code.) Note that Xdummy only works on Linux |
| whereas Xvfb works just about everywhere (and in some situations |
| Xdummy must be run as root.) An advantage of Xdummy over Xvfb is that |
| Xdummy supports RANDR dynamic screen resizing, which can be handy if |
| the user accesses the desktop from different sized screens (e.g. |
| workstation and laptop.) |
| |
| So an inetd(8) example might look like: |
| 5900 stream tcp nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc -inetd \ |
| -o /var/log/x11vnc.log -http -prog /usr/local/bin/x11vnc \ |
| -ssl SAVE -unixpw -users unixpw= -display WAIT:cmd=FINDCREATEDISPLAY |
| |
| Where the very long lines have been split. See below where that long |
| and cumbersome last line is replaced by the -svc alias. |
| |
| The above mode will allow direct SSL (e.g. ss_vncviewer or SSVNC) |
| access and also Java Web browers access via: https://hostname:5900/. |
| |
| Tip: Note that the -create option is an alias for "-display |
| WAIT:cmd=FINDCREATEDISPLAY-Xvfb". |
| |
| Tip: Note that -svc is a short hand for the long "-ssl SAVE -unixpw |
| -users unixpw= -display WAIT:cmd=FINDCREATEDISPLAY" part. Unlike |
| -create, this alias also sets up SSL encryption and Unix password |
| login. |
| |
| The above inetd example then simplifies to: |
| 5900 stream tcp nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc -inetd \ |
| -o /var/log/x11vnc.log -http -prog /usr/local/bin/x11vnc \ |
| -svc |
| |
| Tip: In addition to the usual unixpw parameters, inside the VNC viewer |
| the user can specify after his username (following a ":" see -display |
| WAIT for details) for FINDCREATEDISPLAY they can add "geom=WxH" or |
| "geom=WxHxD" to specify the width, height, and optionally the color |
| depth. E.g. "fred:geom=800x600" at the login: prompt. Also if the env. |
| var X11VNC_CREATE_GEOM is set to the desired WxH or WxHxD that will be |
| used by x11vnc. |
| |
| You can set the env. var X11VNC_SKIP_DISPLAY to a comma separated list |
| of displays to ignore in the FINDDISPLAY process (to force creation of |
| new displays in some cases.) The user logging in via the vncviewer can |
| also set this via username:nodisplay=...) |
| |
| If you do not plan on using the Java Web browser applet you can remove |
| the -http (and -prog) option since this will speed up logging-in by a |
| few seconds (x11vnc will not have to wait to see if a connection is |
| HTTPS or VNC.) |
| |
| For reference, xinetd format in the file, say, /etc/xinetd.d/x11vnc: |
| service x11vnc |
| { |
| type = UNLISTED |
| port = 5900 |
| socket_type = stream |
| protocol = tcp |
| wait = no |
| user = root |
| server = /usr/local/bin/x11vnc |
| server_args = -inetd -o /var/log/x11vnc.log -http -prog /usr/local/ |
| bin/x11vnc -svc |
| disable = no |
| } |
| |
| To print out the script in this case use "-display |
| WAIT:cmd=FINDCREATEDISPLAY-print". To change the preference of |
| Xservers and which to try list them, e.g.: "-display |
| WAIT:cmd=FINDCREATEDISPLAY-X,Xvfb,Xdummy" or use "-create_xsrv |
| X,Xvfb,Xdummy". The "X" one means to try to start up a real, hardware |
| X server, e.g. startx(1) (if there is already a real X server running |
| this may only work on Linux and the chvt program may need to be run to |
| switch to the correct Linux virtual terminal.) x11vnc will try to run |
| chvt automatically if it can determine which VT should be switched to. |
| |
| XDM/GDM/KDM Login Greeter Panel: If you want to present the user with |
| a xdm/gdm/kdm display manager "greeter" login you can use Xvfb.xdmcp |
| instead of Xvfb, etc in the above list. However, you need to configure |
| xdm/gdm/kdm to accept localhost XDMCP messages, this can be done by |
| (from -help output): |
| If you want the FINDCREATEDISPLAY session to contact an XDMCP login |
| manager (xdm/gdm/kdm) on the same machine, then use "Xvfb.xdmcp" |
| instead of "Xvfb", etc. The user will have to supply his username |
| and password one more time (but he gets to select his desktop |
| type so that can be useful.) For this to work, you will need to |
| enable localhost XDMCP (udp port 177) for the display manager. |
| This seems to be: |
| |
| for gdm in gdm.conf: Enable=true in section [xdmcp] |
| for kdm in kdmrc: Enable=true in section [Xdmcp] |
| for xdm in xdm-config: DisplayManager.requestPort: 177 |
| |
| Unless you are also providing XDMCP service to xterminals or other |
| machines, make sure that the host access list only allows local |
| connections (the name of this file is often Xaccess and it is usually |
| setup by default to do just that.) Nowadays, host level firewalling |
| will also typically block UDP (port 177 for XDMCP) by default |
| effectively limiting the UDP connections to localhost. |
| |
| Tip: Note that -xdmsvc is a short hand alias for the long "-ssl SAVE |
| -unixpw -users unixpw= -display |
| WAIT:cmd=FINDCREATEDISPLAY-Xvfb.xdmcp". So we simply use: |
| service x11vnc |
| { |
| type = UNLISTED |
| port = 5900 |
| socket_type = stream |
| protocol = tcp |
| wait = no |
| user = root |
| server = /usr/local/bin/x11vnc |
| server_args = -inetd -o /var/log/x11vnc.log -xdmsvc |
| disable = no |
| } |
| |
| (Note: use "-svc" instead of "-xdmsvc" for no XDMCP login greeter.) |
| |
| |
| Local access (VNC Server and VNC Viewer on the same machine): To |
| access your virtual X display session locally (i.e. while sitting at |
| the same machine it is running on) one can perhaps have something like |
| this in their $HOME/.xinitrc |
| #!/bin/sh |
| x11vnc -create -rfbport 5905 -env WAITBG=1 |
| vncviewer -geometry +0+0 -encodings raw -passwd $HOME/.vnc/passwd localhost:5 |
| |
| You may not need the -passwd. Recent RealVNC viewers might be this: |
| #!/bin/sh |
| x11vnc -create -rfbport 5905 -env WAITBG=1 |
| vncviewer -FullScreen -PreferredEncoding raw -passwd $HOME/.vnc/passwd localhos |
| t:5 |
| |
| This way a bare X server is run with no window manager or desktop; it |
| simply runs only the VNC Viewer on the real X server. The Viewer then |
| draws the virtual X session on to the real one. On your system it |
| might not be $HOME/.xinitrc, but rather .xsession, .Xclients, or |
| something else. You will need to figure out what it is for your system |
| and configuration. |
| |
| There may be a problem if the resolution (WxH) of the virtual X |
| display does not match that of the physical X display. |
| |
| If you do not want to or cannot figure out the X startup script name |
| (.xinitrc, etc) you could save the above commands to a shell script, |
| say "vnclocal", and the log in via the normal KDM or GDM greeter |
| program using the "Failsafe" option. Then in the lone xterm that comes |
| up type "vnclocal" to connect to your virtual X display via x11vnc and |
| vncviewer. |
| |
| _________________________________________________________________ |
| |
| Summary: The "-display WAIT:cmd=FINDCREATEDISPLAY" scheme can be used |
| to provide a "desktop service" (i.e. terminal service) on the server |
| machine: you always get some desktop there, either a real hardware X |
| server or a virtual one (depending on how you set things up.) |
| |
| So it provides simple "terminal services" based on Unix username and |
| password. The created X server sessions (virtual or real hardware) |
| will remain running after you disconnect the VNC viewer and will be |
| found again on reconnecting via VNC and logging in. To terminate them |
| use the normal way to Exit/LogOut from inside your X session. The user |
| does not have to memorize which VNC display number is his. They all go |
| the same one (e.g. hostname:0) and it switches based on username. |
| |
| |
| Q-63: Can I have x11vnc restart itself after it terminates? |
| |
| One could do this in a shell script, but now there is an option -loop |
| that makes it easier. Of course when x11vnc restarts it needs to have |
| permissions to connect to the (potentially new) X display. This mode |
| could be useful if the X server restarts often. Use e.g. "-loop5000" |
| to sleep 5000 ms between restarts. Also "-loop2000,5" to sleep 2000 ms |
| and only restart 5 times. |
| |
| One can also use the -loopbg to emulate inetd(8) to some degree, where |
| each connected process runs in the background. It could be combined, |
| say, with the -svc option to provide simple terminal services without |
| using inetd(8). |
| |
| |
| Q-64: How do I make x11vnc work with the Java VNC viewer applet in a |
| web browser? |
| |
| To have x11vnc serve up a Java VNC viewer applet to any web browsers |
| that connect to it, run x11vnc with this option: |
| -httpdir /path/to/the/java/classes/dir |
| |
| (this directory will contain the files index.vnc and, for example, |
| VncViewer.jar) Note that libvncserver contains the TightVNC Java |
| classes jar file for your convenience. (it is the file |
| classes/VncViewer.jar in the source tree.) |
| |
| You will see output something like this: |
| 14/05/2004 11:13:56 Autoprobing selected port 5900 |
| 14/05/2004 11:13:56 Listening for HTTP connections on TCP port 5800 |
| 14/05/2004 11:13:56 URL http://walnut:5800 |
| 14/05/2004 11:13:56 screen setup finished. |
| 14/05/2004 11:13:56 The VNC desktop is walnut:0 |
| PORT=5900 |
| |
| then you can connect to that URL with any Java enabled browser. Feel |
| free to customize the default index.vnc file in the classes directory. |
| |
| As of May/2005 the -http option will try to guess where the Java |
| classes jar file is by looking in expected locations and ones relative |
| to the x11vnc binary. |
| |
| Also note that if you wanted to, you could also start the Java viewer |
| entirely from the viewer-side by having the jar file there and using |
| either the java or appletviewer commands to run the program. |
| java -cp ./VncViewer.jar VncViewer HOST far-away.east PORT 5900 |
| |
| Proxies: See the discussion here if the web browser must use a web |
| proxy to connect to the internet. It is tricky to get Java applets to |
| work in this case: a signed applet must be used so it can connect to |
| the proxy and ask for the redirection to the VNC server. One way to do |
| this is to use the signed SSL one referred to in classes/ssl/proxy.vnc |
| and set disableSSL=yes (note that this has no encryption; please use |
| SSL or SSH as discuss elsewhere on this page) in the URL or the file. |
| |
| |
| Q-65: Are reverse connections (i.e. the VNC server connecting to the |
| VNC viewer) using "vncviewer -listen" and vncconnect(1) supported? |
| |
| As of Mar/2004 x11vnc supports reverse connections. On Unix one starts |
| the VNC viewer in listen mode: "vncviewer -listen" (see your |
| documentation for Windows, etc), and then starts up x11vnc with the |
| -connect option. To connect immediately at x11vnc startup time use the |
| "-connect host:port" option (use commas for a list of hosts to connect |
| to.) The ":port" is optional (default is VNC listening port is 5500.) |
| |
| If a file is specified instead: -connect /path/to/some/file then that |
| file is checked periodically (about once a second) for new hosts to |
| connect to. |
| |
| The -remote control option (aka -R) can also be used to do this during |
| an active x11vnc session, e.g.: |
| x11vnc -display :0 -R connect:hostname.domain |
| |
| Use the "-connect_or_exit" option to have x11vnc exit if the reverse |
| connection fails. Also, note the "-rfbport 0" option disables TCP |
| listening for connections (potentially useful for reverse connection |
| mode, assuming you do not want any "forward" connections.) |
| |
| Note that as of Mar/2006 x11vnc requires password authentication for |
| reverse connections as well as for forward ones (assuming password |
| auth has been enabled, e.g. via -rfbauth, -passwdfile, etc.) Many VNC |
| servers do not require any password for reverse connections. To regain |
| the old behavior supply this option "-env |
| X11VNC_REVERSE_CONNECTION_NO_AUTH=1" to x11vnc. |
| |
| Vncconnect command: To use the vncconnect(1) program (from the core |
| VNC package at www.realvnc.com) specify the -vncconnect option to |
| x11vnc (Note: as of Dec/2004 -vncconnect is now the default.) |
| vncconnect(1) must be pointed to the same X11 DISPLAY as x11vnc (since |
| it uses X properties to communicate with x11vnc.) If you do not have |
| or do not want to get the vncconnect(1) program, the following script |
| (named "Vncconnect") may work if your xprop(1) supports the -set |
| option: |
| #!/bin/sh |
| # usage: Vncconnect <host> |
| # Vncconnect <host:port> |
| # note: not all xprop(1) support -set. |
| # |
| xprop -root -f VNC_CONNECT 8s -set VNC_CONNECT "$1" |
| |
| |
| Q-66: Can reverse connections be made to go through a Web or SOCKS |
| proxy or SSH? |
| |
| Yes, as of Oct/2007 x11vnc supports reverse connections through |
| proxies: use the "-proxy host:port" option. The default is to assume |
| the proxy is a Web proxy. Note that most Web proxies only allow proxy |
| destination connections to ports 443 (HTTPS) and 563 (SNEWS) and so |
| this might not be too useful unless the proxy has been modified |
| (AllowCONNECT apache setting) or the VNC viewer listens on one of |
| those ports (or the router does a port redir.) A web proxy may also be |
| specified via "-proxy http://host:port" |
| |
| For SOCKS4 and SOCKS4a proxies use this format "-proxy |
| socks://host:port". If the reverse connection hostname is a numerical |
| IP or "localhost" then SOCKS4 (no host lookup) is used, otherwise |
| SOCKS4a will be used. For SOCKS5 (proxy will do lookup and many other |
| things) use "-proxy socks5://host:port". Note that the SSH builtin |
| SOCKS proxy "ssh -D port" only does SOCKS4 or SOCKS5, so use socks5:// |
| for a ssh -D proxy. |
| |
| The proxying works for both SSL encrypted and normal reverse |
| connections. |
| |
| An experimental mode is "-proxy http://host:port/..." where the URL |
| (e.g. a CGI script) is retrieved via the GET method. See -proxy for |
| more info. |
| |
| Another experimental mode is "-proxy ssh://user@host" in which case a |
| SSH tunnel is used for the proxying. See -proxy for more info. |
| |
| Up to 3 proxies may be chained together by listing them by commas |
| e.g.: "-proxy http://host1:port1,socks5://host2:port2" in case one |
| needs to ricochet off of several machines to ultimately reach the |
| listening viewer. |
| |
| |
| Q-67: Can x11vnc provide a multi-user desktop web login service as an |
| Apache CGI or PHP script? |
| Yes. See the example script desktop.cgi for ideas. It is in the source |
| tree in the directory x11vnc/misc. It serves x11vnc's SSL enabled Java |
| Applet to the web browser with the correct connection information for |
| the user's virtual desktop (an Xvfb session via -create; be sure to |
| add the Xvfb package.) HTTPS/SSL enabled Apache should be used to |
| serve the script to avoid unix and vnc passwords from being sent in |
| cleartext and sniffed. |
| |
| By default it uses a separate VNC port for each user desktop (either |
| by autoprobing in a range of ports or using a port based on the userid |
| number.) The web server's firewall must allow incoming connections to |
| these ports. |
| |
| It is somewhat difficult to do all of this with x11vnc listening on a |
| single port, however there is also a 'fixed port' scheme described in |
| the script based on -loopbg that works fairly well (but more |
| experience is needed to see what problems contention for the same port |
| causes; however at worst one user may need to re-login.) |
| |
| There is also an optional 'port redirection' mode for desktop.cgi that |
| allows redirection to other machines inside the firewall already |
| running SSL enabled VNC servers. This provides much of the |
| functionality as the SSL Portal and is easier to set up. |
| |
| |
| Q-68: Can I use x11vnc as a replacement for Xvnc? (i.e. not for a real |
| display, but for a virtual one I keep around.) |
| |
| You can, but you would not be doing this for performance reasons (for |
| virtual X sessions via VNC, Xvnc should give the fastest response.) |
| You may want to do this because Xvnc is buggy and crashes, does not |
| support an X server extension you desire, or you want to take |
| advantage of one of x11vnc's unending number of options and features. |
| |
| One way to achieve this is to have a Xvfb(1) virtual framebuffer X |
| server running in the background and have x11vnc attached to it. |
| Another method, faster and more accurate, is to use the "dummy" Device |
| Driver in XFree86/Xorg (see below.) |
| |
| For these virtual sessions you will need to install the Xvfb program |
| (e.g. apt-get install xvfb) or our Xdummy program (see below.) |
| |
| In either case, one can view this desktop both remotely and also |
| locally using vncviewer. Make sure vncviewer's "-encodings raw" is in |
| effect for local viewing (compression seems to slow things down |
| locally.) For local viewing you set up a "bare" window manager that |
| just starts up vncviewer and nothing else (See how below.) |
| |
| Here is one way to start up Xvfb: |
| xinit -- /usr/bin/Xvfb :1 -cc 4 -screen 0 1024x768x16 |
| |
| This starts up a 16bpp virtual display. To export it via VNC use |
| x11vnc -display :1 ... |
| |
| Then have the remote vncviewer attach to x11vnc's VNC display (e.g. :0 |
| which is port 5900.) |
| |
| The "-cc 4" Xvfb option is to force it to use a TrueColor visual |
| instead of DirectColor (this works around a recent bug in the Xorg |
| Xvfb server.) |
| |
| One good thing about Xvfb is that the virtual framebuffer exists in |
| main memory (rather than in the video hardware), and so x11vnc can |
| "screen scrape" it very efficiently (more than, say, 100X faster than |
| normal video hardware.) |
| |
| Update Nov/2006: See the FINDCREATEDISPLAY discussion of the "-display |
| WAIT:cmd=FINDDISPLAY" option where virtual (Xvfb or Xdummy, or even |
| real ones by changing an option) X servers are started automatically |
| for new users connecting. This provides a "desktop service" for the |
| machine. You either get your real X session or your virtual |
| (Xvfb/Xdummy) one whenever you connect to the machine (inetd(8) is a |
| nice way to provide this service.) The -find, -create, -svc, and |
| -xdmsvc aliases can also come in handy here. |
| |
| There are some annoyances WRT Xvfb however. The default keyboard |
| mapping seems to be very poor. One should run x11vnc with -add_keysyms |
| option to have keysyms added automatically. Also, to add the Shift_R |
| and Control_R modifiers something like this is needed: |
| #!/bin/sh |
| xmodmap -e "keycode any = Shift_R" |
| xmodmap -e "add Shift = Shift_L Shift_R" |
| xmodmap -e "keycode any = Control_R" |
| xmodmap -e "add Control = Control_L Control_R" |
| xmodmap -e "keycode any = Alt_L" |
| xmodmap -e "keycode any = Alt_R" |
| xmodmap -e "keycode any = Meta_L" |
| xmodmap -e "add Mod1 = Alt_L Alt_R Meta_L" |
| |
| (note: these are applied automatically in the FINDCREATEDISPLAY mode |
| of x11vnc.) Perhaps the Xvfb options -xkbdb or -xkbmap could be used |
| to get a better default keyboard mapping... |
| |
| Dummy Driver: A user points out a faster and more accurate method is |
| to use the "dummy" Device Driver of XFree86/Xorg instead of Xvfb. He |
| uses this to create a persistent and resizable desktop accessible from |
| anywhere. In the Device Section of the config file set Driver "dummy". |
| You may also need to set VideoRam NNN to be large enough to hold the |
| framebuffer. The framebuffer is kept in main memory like Xvfb except |
| that the server code is closely correlated with the real XFree86/Xorg |
| Xserver unlike Xvfb. |
| |
| The main drawback to this method (besides requiring extra |
| configuration and possibly root permission) is that it also does the |
| Linux Virtual Console/Terminal (VC/VT) switching even though it does |
| not need to (since it doesn't use a real framebuffer.) There are some |
| "dual headed" (actually multi-headed/multi-user) patches to the X |
| server that turn off the VT usage in the X server. Update: As of |
| Jul/2005 we have an LD_PRELOAD script Xdummy that allows you to use a |
| stock (i.e. unpatched) Xorg or XFree86 server with the "dummy" driver |
| and not have any VT switching problems! An advantage of Xdummy over |
| Xvfb is that Xdummy supports RANDR dynamic screen resizing. |
| |
| The standard way to start the "dummy" driver would be: |
| startx -- :1 -config /etc/X11/xorg.conf.dummy |
| |
| where the file /etc/X11/xorg.conf.dummy has its Device Section |
| modified as described above. To use the LD_PRELOAD wrapper script: |
| startx -- /path/to/Xdummy :1 |
| |
| An xdm(1) example is also provided. |
| |
| In general, one can use these sorts of schemes to use x11vnc to export |
| other virtual X sessions, say Xnest or even Xvnc itself (useful for |
| testing x11vnc.) |
| |
| Local access (VNC Server and VNC Viewer on the same machine): You use |
| a VNC viewer to access the display remotely; to access your virtual X |
| display locally (i.e. while sitting at the same machine it is running |
| on) one can perhaps have something like this in their $HOME/.xinitrc |
| #!/bin/sh |
| x11vnc -display :5 -rfbport 5905 -bg |
| vncviewer -geometry +0+0 -encodings raw -passwd $HOME/.vnc/passwd localhost:5 |
| |
| The display numbers (VNC and X) will likely be different (you could |
| also try -find), and you may not need the -passwd. Recent RealVNC |
| viewers might be this: |
| #!/bin/sh |
| x11vnc -display :5 -rfbport 5905 -bg |
| vncviewer -FullScreen -PreferredEncoding raw -passwd $HOME/.vnc/passwd localhos |
| t:5 |
| |
| This way a bare X server is run with no window manager or desktop; it |
| simply runs only the VNC Viewer on the real X server. The Viewer then |
| draws the virtual X session on to the real one. On your system it |
| might not be $HOME/.xinitrc, but rather .xsession, .Xclients, or |
| something else. You will need to figure out what it is for your system |
| and configuration. |
| |
| |
| XDM/GDM/KDM One-Shot X sessions: For the general replacement of Xvnc |
| by Xvfb+x11vnc, one user describes a similar setup he created where |
| the X sessions are one-shot's (destroyed after the vncviewer |
| disconnects) and it uses the XDM/GDM/KDM login greeter here. |
| |
| |
| Q-69: How can I use x11vnc on "headless" machines? Why might I want |
| to? |
| |
| An interesting application of x11vnc is to let it export displays of |
| "headless" machines. For example, you may have some lab or server |
| machines with no keyboard, mouse, or monitor, but each one still has a |
| video card. One can use x11vnc to provide a simple "desktop service" |
| from these server machines. |
| |
| An X server can be started on the headless machine (sometimes this |
| requires configuring the X server to not fail if it cannot detect a |
| keyboard or mouse, see the next paragraph.) Then you can export that X |
| display via x11vnc (e.g. see this FAQ) and access it from anywhere on |
| the network via a VNC viewer. |
| |
| Some tips on getting X servers to start on machines without keyboard |
| or mouse: For XFree86/Xorg the Option "AllowMouseOpenFail" "true" |
| "ServerFlags" config file option is useful. On Solaris Xsun the |
| +nkeyboard and +nmouse options are useful (put them in the server |
| command line args in /etc/dt/config/Xservers.) There are patches |
| available for Xsun at lease back to Solaris 8 that support this. See |
| Xserver(1) for more info. |
| |
| Although this usage may sound strange it can be quite useful for a GUI |
| (or other) testing or QA setups: the engineers do not need to walk to |
| lab machines running different hardware, OS's, versions, etc (or have |
| many different machines in their office.) They just connect to the |
| various test machines over the network via VNC. The advantage to |
| testing this way instead of using Xvnc or even Xvfb is that the test |
| is done using the real X server, fonts, video hardware, etc. that will |
| be used in the field. |
| |
| One can imagine a single server machine crammed with as many video |
| cards as it can hold to provide multiple simultaneous access or |
| testing on different kinds of video hardware. |
| |
| See also the FINDCREATEDISPLAY discussion of the "-display |
| WAIT:cmd=FINDDISPLAY" option where virtual Xvfb or Xdummy, or real X |
| servers are started automatically for new users connecting. The -find, |
| -create, -svc, and -xdmsvc aliases can also come in handy here. |
| |
| [Resource Usage and Performance] |
| |
| Q-70: I have lots of memory, but why does x11vnc fail with shmget: |
| No space left on device or Minor opcode of failed request: 1 |
| (X_ShmAttach)? |
| |
| It is not a matter of free memory, but rather free shared memory (shm) |
| slots, also known as shm segments. This often occurs on a public |
| Solaris machine using the default of only 100 slots. You (or the owner |
| or root) can clean them out with ipcrm(1). x11vnc tries hard to |
| release its slots, but it, and other programs, are not always able to |
| (e.g. if kill -9'd.) |
| |
| Sometimes x11vnc will notice the problem with shm segments and tries |
| to get by with fewer, only giving a warning like this: |
| 19/03/2004 10:10:58 shmat(tile_row) failed. |
| shmat: Too many open files |
| 19/03/2004 10:10:58 error creating tile-row shm for len=4 |
| 19/03/2004 10:10:58 reverting to single_copytile mode |
| |
| Here is a shell script shm_clear to list and prompt for removal of |
| your unattached shm segments (attached ones are skipped.) I use it |
| while debugging x11vnc (I use "shm_clear -y" to assume "yes" for each |
| prompt.) If x11vnc is regularly not cleaning up its shm segments, |
| please contact me so we can work to improve the situation. |
| |
| Longer term, on Solaris you can put something like this in |
| /etc/system: |
| set shmsys:shminfo_shmmax = 0x2000000 |
| set shmsys:shminfo_shmmni = 0x1000 |
| |
| to sweep the problem under the rug (4096 slots.) On Linux, examine |
| /proc/sys/kernel/shmmni; you can modify the value by writing to that |
| file. |
| |
| Things are even more tight on Solaris 8 and earlier, there is a |
| default maximum number of shm segments per process of 6. The error is |
| the X server (not x11vnc) being unable to attach to the segments, and |
| looks something like this: |
| 30/04/2004 14:04:26 Got connection from client 192.168.1.23 |
| 30/04/2004 14:04:26 other clients: |
| X Error of failed request: BadAccess (attempt to access private resource den |
| ied) |
| Major opcode of failed request: 131 (MIT-SHM) |
| Minor opcode of failed request: 1 (X_ShmAttach) |
| Serial number of failed request: 14 |
| Current serial number in output stream: 17 |
| |
| This tight limit on Solaris 8 can be increased via: |
| set shmsys:shminfo_shmseg = 100 |
| |
| in /etc/system. See the next paragraph for more workarounds. |
| |
| To minimize the number of shm segments used by x11vnc try using the |
| -onetile option (corresponds to only 3 shm segments used, and adding |
| -fs 1.0 knocks it down to 2.) If you are having much trouble with shm |
| segments, consider disabling shm completely via the -noshm option. |
| Performance will be somewhat degraded but when done over local machine |
| sockets it should be acceptable (see an earlier question discussing |
| -noshm.) |
| |
| |
| Q-71: How can I make x11vnc use less system resources? |
| |
| The -nap (now on by default; use -nonap to disable) and "-wait n" |
| (where n is the sleep between polls in milliseconds, the default is 30 |
| or so) option are good places to start. In addition, something like |
| "-sb 15" will cause x11vnc to go into a deep-sleep mode after 15 |
| seconds of no activity (instead of the default 60.) |
| |
| Reducing the X server bits per pixel depth (e.g. to 16bpp or even |
| 8bpp) will further decrease memory I/O and network I/O. The ShadowFB X |
| server setting will make x11vnc's screen polling less severe. Using |
| the -onetile option will use less memory and use fewer shared memory |
| slots (add -fs 1.0 for one less slot.) |
| |
| |
| Q-72: How can I make x11vnc use MORE system resources? |
| |
| You can try -threads (note this mode can be unstable and/or crash; and |
| as of May/2008 is strongly discouraged, see the option description) or |
| dial down the wait time (e.g. -wait 1) and possibly dial down -defer |
| as well. Note that if you try to increase the "frame rate" too much |
| you can bog down the server end with the extra work it needs to do |
| compressing the framebuffer data, etc. |
| |
| That said, it is possible to "stream" video via x11vnc if the video |
| window is small enough. E.g. a 256x192 xawtv TV capture window (using |
| the x11vnc -id option) can be streamed over a LAN or wireless at a |
| reasonable frame rate. If the graphics card's framebuffer read rate is |
| faster than normal then the video window size and frame rate can be |
| much higher. The use of TurboVNC and/or TurboJPEG can make the frame |
| rate somewhat higher still (but most of this hinges on the graphics |
| card's read rate.) |
| |
| |
| Q-73: I use x11vnc over a slow link with high latency (e.g. dialup |
| modem or broadband), is there anything I can do to speed things up? |
| |
| Some things you might want to experiment with (many of which will help |
| performance on faster links as well): |
| |
| X server/session parameters: |
| * Configure the X server bits per pixel to be 16bpp or even 8bpp. |
| (reduces amount of data needed to be polled, compressed, and sent) |
| * Use a smaller desktop size (e.g. 1024x768 instead of 1280x1024) |
| * Make sure the desktop background is a solid color (the background |
| is resent every time it is re-exposed.) Consider using the -solid |
| [color] option to try to do this automatically. |
| * Configure your window manager or desktop "theme" to not use fancy |
| images, shading, and gradients for the window decorations, etc. |
| Disable window animations, etc. Maybe your desktop has a "low |
| bandwidth" theme you can easily switch into and out of. Also in |
| Firefox disable eye-candy, e.g.: Edit -> Preferences -> Advanced |
| -> Use Smooth Scrolling (deselect it.) |
| * Avoid small scrolls of large windows using the Arrow keys or |
| scrollbar. Try to use PageUp/PageDown instead. (not so much of a |
| problem in x11vnc 0.7.2 if -scrollcopyrect is active and detecting |
| scrolls for the application.) |
| * If the -wireframe option is not available (earlier than x11vnc |
| 0.7.2 or you have disabled it via -nowireframe) then Disable |
| Opaque Moves and Resizes in the window manager/desktop. |
| * However if -wireframe is active (on by default in x11vnc 0.7.2) |
| then you should Enable Opaque Moves and Resizes in the window |
| manager! This seems counter-intuitive, but because x11vnc detects |
| the move/resize events early there is a huge speedup over a slow |
| link when Opaque Moves and Resizes are enabled. (e.g. CopyRect |
| encoding will be used.) |
| * Turn off Anti-aliased fonts on your system, web browser, terminal |
| windows, etc. AA fonts do not compress as well as traditional |
| fonts (sometimes 10X less.) |
| * On Firefox/Mozilla (and anything else) turn off "Smooth Scroll" |
| animations. In Firefox put in the URL "about:config" and set |
| general.smoothScroll to false. |
| * On Xorg/XFree86 turn on the Shadow Framebuffer to speed up |
| reading. (Option "ShadowFB" "true" in the Device section of |
| /etc/X11/XF86Config) This disables 2D acceleration on the physical |
| display and so may not be worth it (if you play games, etc), but |
| could be of use in some situations. Note: If the network link is |
| very slow, this speedup may not be noticed. |
| |
| VNC viewer parameters: |
| * Use a TightVNC enabled viewer! (Actually, RealVNC 4.x viewer with |
| ZRLE encoding is not too bad either; some claim it is faster.) |
| * Make sure the tight (or zrle) encoding is being used (look at |
| vncviewer and x11vnc outputs) |
| * Request 8 bits per pixel using -bgr233 (up to 4X speedup over |
| depth 24 TrueColor (32bpp), but colors will be off) |
| * RealVNC 4.x viewer has some extremely low color modes (only 64 and |
| even 8 colors.) SSVNC does too. The colors are poor, but it is |
| usually noticeably faster than bgr233 (256 colors.) |
| * Try increasing the TightVNC -compresslevel (compresses more on |
| server side before sending, but uses more CPU) |
| * Try reducing the TightVNC -quality (increases JPEG compression, |
| but is lossy with painting artifacts) |
| * Try other VNC encodings via -encodings (tight may be the fastest, |
| but you should compare it to zrle and maybe some of the others) |
| * On the machine where vncviewer is run, make sure Backing Store is |
| enabled (Xorg/XFree86 disables it by default causing re-exposures |
| of vncviewer to be very slow) Option "backingstore" in config |
| file. |
| |
| x11vnc parameters: |
| * Make sure the -wireframe option is active (it should be on by |
| default) and you have Opaque Moves/Resizes Enabled in the window |
| manager. |
| * Make sure the -scrollcopyrect option is active (it should be on by |
| default.) This detects scrolls in many (but not all) applications |
| an applies the CopyRect encoding for a big speedup. |
| * Enforce a solid background when VNC viewers are connected via |
| -solid |
| * Try x11vnc's client-side caching client-side caching scheme: |
| -ncache |
| * Specify -speeds modem to force the wireframe and scrollcopyrect |
| heuristic parameters (and any future ones) to those of a dialup |
| modem connection (or supply the rd,bw,lat numerical values that |
| characterize your link.) |
| * If wireframe and scrollcopyrect aren't working, try using the more |
| drastic -nodragging (no screen updates when dragging mouse, but |
| sometimes you miss visual feedback) |
| * Set -fs 1.0 (disables fullscreen updates) |
| * Try increasing -wait or -defer (reduces the maximum "frame rate", |
| but won't help much for large screen changes) |
| * Try the -progressive pixelheight mode with the block pixelheight |
| 100 or so (delays sending vertical blocks since they may change |
| while viewer is receiving earlier ones) |
| * If you just want to watch one (simple) window use -id or -appshare |
| (cuts down extraneous polling and updates, but can be buggy or |
| insufficient) |
| * Set -nosel (disables all clipboard selection exchange) |
| * Use -nocursor and -nocursorpos (repainting the remote cursor |
| position and shape takes resources and round trips) |
| * On very slow links (e.g. <= 28.8) you may need to increase the |
| -readtimeout n setting if it sometimes takes more than 20sec to |
| paint the full screen, etc. |
| * Do not use -fixscreen to automatically refresh the whole screen, |
| tap three Alt_L's then the screen has painting errors (rare |
| problem.) |
| |
| |
| Example for the KDE desktop: |
| |
| Launch the "KDE Control Center" utility. Sometimes this is called |
| "Personal Settings". |
| |
| Select "Desktop". |
| |
| Then Select "Window Behavior". In the "Moving" Tab set these: |
| * YES - Display content in moving windows |
| * YES - Display content in resizing windows |
| * NO - Display window geometry when moving or resizing |
| * NO - Animate minimize and restore |
| |
| In the "Translucency" Tab set: |
| * NO - Use translucency/shadows |
| |
| Next hit "Back" and then select "Panels". |
| |
| In the "Appearance" Tab set: |
| * NO - Enable icon mouseover effects |
| * NO - Enable transparency |
| |
| Now go all the way back up to the top and Select "Appearance & |
| Themes". |
| |
| Select "Background" and set: |
| * YES - No picture |
| * Colors: Single Color |
| |
| Select "Fonts" and disable anti-aliased fonts if you are bold enough. |
| |
| Select "Launch Feedback" and set: |
| * Busy Cursor: No Busy Cursor |
| * NO - Enable taskbar notification |
| |
| Select "Screen Saver" and set: |
| * Screen Saver: Blank Screen |
| |
| Select "Style" and in the "Effects" Tab set: |
| * NO - Enable GUI effects |
| |
| |
| Example for the GNOME desktop: |
| * TBD. |
| |
| |
| Q-74: Does x11vnc support the X DAMAGE Xserver extension to find |
| modified regions of the screen quickly and efficiently? |
| |
| Yes, as of Mar/2005 x11vnc will use the X DAMAGE extension by default |
| if it is available on the display. This requires libXdamage to be |
| available in the build environment as well (recent Linux distros and |
| Solaris 10 have it.) |
| |
| The DAMAGE extension enables the X server to report changed regions of |
| the screen back to x11vnc. So x11vnc doesn't have to guess where the |
| changes are (by polling every pixel of the entire screen every 2-4 |
| seconds.) The use of X DAMAGE dramatically reduces the load when the |
| screen is not changing very much (i.e. most of the time.) It also |
| noticeably improves updates, especially for very small changed areas |
| (e.g. clock ticking, cursor flashing, typing, etc.) |
| |
| Note that the DAMAGE extension does not speed up the actual reading of |
| pixels from the video card framebuffer memory, by, say, mirroring them |
| in main memory. So reading the fb is still painfully slow (e.g. |
| 5MB/sec), and so even using X DAMAGE when large changes occur on the |
| screen the bulk of the time is still spent retrieving them. Not ideal, |
| but use of the ShadowFB XFree86/Xorg option speeds up the reading |
| considerably (at the cost of h/w acceleration.) |
| |
| Unfortunately the current Xorg DAMAGE extension implementation can at |
| times be overly conservative and report very large rectangles as |
| "damaged" even though only a small portion of the pixels have actually |
| been modified. This behavior is often the fault of the window manager |
| (e.g. it redraws the entire, unseen, frame window underneath the |
| application window when it gains focus), or the application itself |
| (e.g. does large, unnecessary repaints.) |
| |
| To work around this deficiency, x11vnc currently only trusts small |
| DAMAGE rectangles to contain real damage. The larger rectangles are |
| only used as hints to focus the traditional scanline polling (i.e. if |
| a scanline doesn't intersect a recent DAMAGE rectangle, the scan is |
| skipped.) You can use the "-xd_area A" option to adjust the size of |
| the trusted DAMAGE rectangles. The default is 20000 pixels (e.g. a |
| 140x140 square, etc.) Use "-xd_area 0" to disable the cutoff and trust |
| all DAMAGE rectangles. |
| |
| The option "-xd_mem f" may also be of use in tuning the algorithm. To |
| disable using DAMAGE entirely use "-noxdamage". |
| |
| |
| Q-75: My OpenGL application shows no screen updates unless I supply |
| the -noxdamage option to x11vnc. |
| One user reports in his environment (MythTV using the NVIDIA OpenGL |
| drivers) he gets no updates after the initial screen is drawn unless |
| he uses the "-noxdamage" option. |
| |
| This seems to be a bug in the X DAMAGE implementation of that driver. |
| You may have to use -noxdamage as well. A way to autodetect this will |
| be tried, probably the best it will do is automatically stop using X |
| DAMAGE. |
| |
| A developer for MiniMyth reports that the 'alphapulse' tag of the |
| theme G.A.N.T. can also cause problems, and should be avoided when |
| using VNC. |
| |
| Update: see this FAQ too. |
| |
| |
| Q-76: When I drag windows around with the mouse or scroll up and down |
| things really bog down (unless I do the drag in a single, quick |
| motion.) Is there anything to do to improve things? |
| |
| This problem is primarily due to slow hardware read rates from video |
| cards: as you scroll or move a large window around the screen changes |
| are much too rapid for x11vnc to keep up them (it can usually only |
| read the video card at about 5-10 MB/sec, so it can take a good |
| fraction of a second to read the changes induce from moving a large |
| window, if this to be done a number of times in succession the window |
| or scroll appears to "lurch" forward.) See the description in the |
| -pointer_mode option for more info. The next bottleneck is compressing |
| all of these changes and sending them out to connected viewers, |
| however the VNC protocol is pretty much self-adapting with respect to |
| that (updates are only packaged and sent when viewers ask for them.) |
| |
| As of Jan/2004 there are some improvements to libvncserver. The |
| default should now be much better than before and dragging small |
| windows around should no longer be a huge pain. If for some reason |
| these changes make matters worse, you can go back to the old way via |
| the "-pointer_mode 1" option. |
| |
| Also added was the -nodragging option that disables all screen updates |
| while dragging with the mouse (i.e. mouse motion with a button held |
| down.) This gives the snappiest response, but might be undesired in |
| some circumstances when you want to see the visual feedback while |
| dragging (e.g. menu traversal or text selection.) |
| |
| As of Dec/2004 the -pointer_mode n option was introduced. n=1 is the |
| original mode, n=2 an improvement, etc.. See the -pointer_mode n help |
| for more info. |
| |
| Also, in some circumstances the -threads option can improve response |
| considerably. Be forewarned that if more than one vncviewer is |
| connected at the same time then libvncserver may not be thread safe |
| (try to get the viewers to use different VNC encodings, e.g. tight and |
| ZRLE.) This option can be unstable and so as of Feb/2008 it is |
| disabled by default. Set env. X11VNC_THREADED=1 to re-enable. |
| |
| As of Apr/2005 two new options (see the wireframe FAQ and |
| scrollcopyrect FAQ below) provide schemes to sweep this problem under |
| the rug for window moves or resizes and for some (but not all) window |
| scrolls. These are the preferred way of avoiding the "lurching" |
| problem, contact me if they are not working. Note on SuSE and some |
| other distros the RECORD X extension used by scrollcopyrect is not |
| enabled by default, turn it on in xorg.conf: |
| Section "Module" |
| ... |
| Load "record" |
| ... |
| EndSection |
| |
| |
| Q-77: Why not do something like wireframe animations to avoid the |
| windows "lurching" when being moved or resized? |
| |
| Nice idea for a hack! As of Apr/2005 x11vnc by default will apply |
| heuristics to try to guess if a window is being (opaquely) moved or |
| resized. If such a change is detected framebuffer polling and updates |
| will be suspended and only an animated "wireframe" (a rectangle |
| outline drawn where the moved/resized window would be) is shown. When |
| the window move/resize stops, it returns to normal processing: you |
| should only see the window appear in the new position. This spares you |
| from interacting with a "lurching" window between all of the |
| intermediate steps. BTW the lurching is due to slow video card read |
| rates (see here too.) A displacement, even a small one, of a large |
| window requires a non-negligible amount of time, a good fraction of a |
| second, to read in from the hardware framebuffer. |
| |
| Note that Opaque Moves/Resizes must be Enabled by your window manager |
| for -wireframe to do any good. |
| |
| The mode is currently on by default because most people are afflicted |
| with the problem. It can be disabled with the -nowireframe option (aka |
| -nowf.) Why might one want to turn off the wireframing? Since x11vnc |
| is merely guessing when windows are being moved/resized, it may guess |
| poorly for your window-manager or desktop, or even for the way you |
| move the pointer. If your window-manager or desktop already does its |
| own wireframing then this mode is a waste of time and could do the |
| wrong thing occasionally. There may be other reasons the new mode |
| feels unnatural. If you have very expensive video hardware (SGI, well |
| now even proprietary Xorg drivers are fast at reading) or are using an |
| in-RAM video framebuffer (SunRay, ShadowFB, Xvfb), the read rate from |
| that framebuffer may be very fast (100's of MB/sec) and so you don't |
| really see much lurching (at least over a fast LAN): opaque moves look |
| smooth in x11vnc. Note: ShadowFB is often turned on when you are using |
| the vesafb or fbdev XFree86 video driver instead of a native one so |
| you might be using it already and not know. |
| |
| The heuristics used to guess window motion or resizing are simple, but |
| are not fool proof: x11vnc is sometimes tricked and so you'll |
| occasionally see the lurching opaque move and rarely something even |
| worse. |
| |
| First it assumes that the move/resize will occur with a mouse button |
| pressed, held down and dragged (of course this is only mostly true.) |
| Next it will only consider a window for wireframing if the mouse |
| pointer is initially "close enough" to the edges of the window frame, |
| e.g. you have grabbed the title bar or a resizer edge (this |
| requirement can be disabled and it also not applied if a modifier key, |
| e.g. Alt, is pressed.) If these are true, it will wait an amount of |
| time to see if the window starts moving or resizing. If it does, it |
| starts drawing the wireframe "outline" of where the window would be. |
| When the mouse button is released, or a timeout occurs, it goes back |
| to the standard mode to allow the actual framebuffer changes to |
| propagate to the viewers. |
| |
| These parameters can be tweaked: |
| * Color/Shade of the wireframe. |
| * Linewidth of the outline frame. |
| * Cutoff size of windows to not apply wireframing to. |
| * Cutoffs for closeness to Top, Bottom, Left, and Right edges of |
| window. |
| * Modifier keys to enable interior window grabbing. |
| * Maximum time to wait for dragging pointer events. |
| * Maximum time to wait for the window to start moving/resizing. |
| * Maximum time to show a wireframe animation. |
| * Minimum time between sending wireframe outlines. |
| |
| See the "-wireframe tweaks" option for more details. On a slow link, |
| e.g. dialup modem, the parameters may be automatically adjusted for |
| better response. |
| |
| |
| CopyRect encoding: In addition to the above there is the |
| "-wirecopyrect mode" option. It is also on by default. This instructs |
| x11vnc to not only show the wireframe animation, but to also instruct |
| all connected VNC viewers to locally translate the window image data |
| from the original position to the new position on the screen when the |
| animation is done. This speedup is the VNC CopyRect encoding: the |
| framebuffer update doesn't need to send the actual new image data. |
| This is nice in general, and very convenient over a slow link, but |
| since it is based on heuristics you may need to disable it with the |
| -nowirecopyrect option (aka -nowcr) if it works incorrectly or |
| unnaturally for you. |
| |
| The -wirecopyrect modes are: "never" (same as -nowirecopyrect); "top", |
| only apply the CopyRect if the window is appears to be on the top of |
| the window stack and is not obstructed by other windows; and "always" |
| to always try to apply the CopyRect (obstructed regions are usually |
| clipped off and not translated.) |
| |
| Note that some desktops (KDE and xfce) appear to mess with the window |
| stacking in ways that are not yet clear. In these cases x11vnc works |
| around the problem by applying the CopyRect even if obscuring windows' |
| data is translated! Use -nowirecopyrect if this yields undesirable |
| effects for your desktop. |
| |
| Also, the CopyRect encoding may give incorrect results under -scale |
| (depending on the scale factor the CopyRect operation is often only |
| approximate: the correctly scaled framebuffer will be slightly |
| different from the translated one.) x11vnc will try to push a |
| "cleanup" update after the CopyRect if -scale is in effect. Use |
| -nowirecopyrect if this or other painting errors are unacceptable. |
| |
| |
| Q-78: Can x11vnc try to apply heuristics to detect when a window is |
| scrolling its contents and use the CopyRect encoding for a speedup? |
| |
| Another nice idea for a hack! As of May/2005 x11vnc will by default |
| apply heuristics to try to detect if the window that has the input |
| focus is scrolling its contents (but only when x11vnc is feeding user |
| input, keystroke or pointer, to the X server.) So, when detected, |
| scrolls induced by dragging on a scrollbar or by typing (e.g. Up or |
| Down arrows, hitting Return in a terminal window, etc), will show up |
| much more quickly than via the standard x11vnc screen polling update |
| mechanism. |
| |
| There will be a speedup for both slow and fast links to viewers. For |
| slow links the speedup is mostly due to the CopyRect encoding not |
| requiring the image data to be transmitted over the network. For fast |
| links the speedup is primarily due to x11vnc not having to read the |
| scrolled framebuffer data from the X server (recall that reading from |
| the hardware framebuffer is slow.) |
| |
| To do this x11vnc uses the RECORD X extension to snoop the X11 |
| protocol between the X client with the focus window and the X server. |
| This extension is usually present on most X servers (but SuSE disables |
| it for some reason.) On XFree86/Xorg it can be enabled via Load |
| "record" in the Module section of the config file if it isn't already: |
| Section "Module" |
| ... |
| Load "record" |
| ... |
| EndSection |
| |
| Currently the RECORD extension is used as little as possible so as to |
| not slow down regular use. Only simple heuristics are applied to |
| detect XCopyArea and XConfigureWindow calls from the application. |
| These catch a lot of scrolls, e.g. in mozilla/firefox and in terminal |
| windows like gnome-terminal and xterm. Unfortunately the toolkits KDE |
| applications use make scroll detection less effective (only rarely are |
| they detected: i.e. Konqueror and Konsole don't work.) An interesting |
| project, that may be the direction x11vnc takes, is to record all of |
| the X11 protocol from all clients and try to "tee" the stream into a |
| modified Xvfb watching for CopyRect and other VNC speedups. A |
| potential issue is the RECORD stream is delayed from actual view on |
| the X server display: if one falls too far behind it could become a |
| mess... |
| |
| The initial implementation of -scrollcopyrect option is useful in that |
| it detects many scrolls and thus gives a much nicer working |
| environment (especially when combined with the -wireframe |
| -wirecopyrect options, which are also on by default; and if you are |
| willing to enable the ShadowFB things are very fast.) The fact that |
| there aren't long delays or lurches during scrolling is the primary |
| improvement. |
| |
| But there are some drawbacks: |
| * Not all scrolls are detected. Some apps scroll windows in ways |
| that cannot currently be detected, and other times x11vnc "misses" |
| the scroll due to timeouts, etc. Sometimes it is more distracting |
| that a speedup occasionally doesn't work as opposed to being |
| consistently slow! |
| * For rapid scrolling (i.e. sequence of many scrolls over a short |
| period) there can be painting errors (tearing, bunching up, etc.) |
| during the scroll. These will repair themselves after the scroll |
| is over, but when they are severe it can be distracting. Try to |
| think of the approximate window contents as a quicker and more |
| useful "animation" compared to the slower polling scheme... |
| * Scrolling inside shells in terminal windows (gnome-terminal, |
| xterm), can lead to odd painting errors. This is because x11vnc |
| did not have time to detect a screen change just before the scroll |
| (most common is the terminal undraws the block cursor before |
| scrolling the text up: in the viewer you temporarily see multiple |
| block cursors.) Another issue is with things like more(1): scroll |
| detection for 5-6 lines happens nicely, but then it can't keep up |
| and so there is a long pause for the standard polling method to |
| deliver the remaining updates. |
| * More rarely sometimes painting errors are not repaired after the |
| scroll is over. This may be a bug in x11vnc or libvncserver, or it |
| may be an inescapable fact of the CopyRect encoding and the delay |
| between RECORD callbacks and what is actually on the X display. |
| One can tap the Alt_L key (Left "Alt" key) 3 times in a row to |
| signal x11vnc to refresh the screen to all viewers. Your |
| VNC-viewer may have its own screen refresh hot-key or button. See |
| also: -fixscreen |
| * Some applications, notably OpenOffice, do XCopyArea scrolls in |
| weird ways that assume ancestor window clipping is taking place. |
| See the -scr_skip option for ways to tweak this on a |
| per-application basis. |
| * Selecting text while dragging the mouse may be slower, especially |
| if the Button-down event happens near the window's edge. This is |
| because the scrollcopyrect scheme is watching for scrolls via |
| RECORD and has to wait for a timeout to occur before it does the |
| update. |
| * For reasons not yet understood the RECORD extension can stop |
| responding (and hence scrolls are missed.) As a workaround x11vnc |
| attempts to reset the RECORD connection every 60 seconds or so. |
| Another workaround is to type 4 Super_L (Left Super/Windows-Flag |
| key) in a row to reset RECORD. Work is in progress to try to fix |
| this bug. |
| * Sometimes you need to "retrain" x11vnc for a certain window |
| because it fails to detect scrolls in it. Sometimes clicking |
| inside the application window or selecting some text in it to |
| force the focus helps. |
| * When using the -scale option there will be a quick CopyRect |
| scroll, but it needs to be followed by a slower "cleanup" update. |
| This is because for a fixed finite screen resolution (e.g. 75 dpi) |
| scaling and copyrect-ing are not exactly independent. Scaling |
| involves a blending of nearby pixels and if you translate a pixel |
| the neighbor pixel weighting may be different. So you have to wait |
| a bit for the cleanup update to finish. On slow links x11vnc may |
| automatically decide to not detect scrolls when -scale is in |
| effect. In general it will also try to defer the cleanup update if |
| possible. |
| |
| If you find the -scrollcopyrect behavior too approximate or |
| distracting you can go back to the standard polling-only update method |
| with the -noscrollcopyrect (or -noscr for short.) If you find some |
| extremely bad and repeatable behavior for -scrollcopyrect please |
| report a bug. |
| |
| Alternatively, as with -wireframe, there are many tuning parameters to |
| try to improve the situation. You can also access these parameters |
| inside the gui under "Tuning". These parameters can be tweaked: |
| * The minimum pixel area of a rectangle to be watched for scrolls. |
| * A list if application names to skip scroll detection. |
| * Which keystrokes should trigger scroll detection. |
| * Which applications should have a "terminal" tweak applied to them. |
| * When repeating keys (e.g. Up arrow) should be discarded to |
| preserve a scroll. |
| * Cutoffs for closeness to Top, Bottom, Left, and Right edges of |
| window for mouse induced scrolls. |
| * Set timeout parameters for keystroke induced scrolls. |
| * Set timeout parameters for mouse pointer induced scrolls. |
| * Have the full screen be periodically refreshed to fix painting |
| errors. |
| |
| |
| Q-79: Can x11vnc do client-side caching of pixel data? I.e. so when |
| that pixel data is needed again it does not have to be retransmitted |
| over the network. |
| |
| As of Dec/2006 in the 0.9 development tarball there is an experimental |
| client-side caching implementation enabled by the "-ncache n" option. |
| In fact, during the test period it was on by default with n set to 10. |
| To disable it use "-noncache". |
| |
| It is a simple scheme where a (very large) lower portion of the |
| framebuffer (i.e. starting just below the user's actual desktop |
| display) is used for storing pixel data. CopyRect; a fast, essentially |
| local viewer-side VNC encoding; is used to swap the pixel data in and |
| out of the actual display area. It gives an excellent speedup for |
| iconifying/deiconifying and moving windows and re-posting of menus |
| (often it doesn't feel like VNC at all: there is no delay waiting for |
| the pixel data to fill in.) |
| |
| This scheme is nice because it does all of this within the existing |
| VNC protocol, and so it works with all VNC viewers. |
| |
| A challenge to doing more sophisticated (e.g. compressed and/or |
| shared) client-side caching is that one needs to extend the VNC |
| protocol, modify a viewer and then also convince users to adopt your |
| modified VNC Viewer (or get the new features to be folded into the |
| main VNC viewers, patches accepted, etc... likely takes many years |
| before they might be deployed in the field.) So it is convenient that |
| the "-ncache n" works with any unaltered VNC viewer. |
| |
| A drawback of the "-ncache n" method is that in the VNC Viewer you can |
| scroll down and actually see the cached pixel data. So it looks like |
| there is a bug: you can scroll down in your viewer and see a strange |
| "history" of windows on your desktop. This is working as intended. One |
| will need to try to adjust the size of his VNC Viewer window so the |
| cache area cannot be seen. SSVNC (see below) can do this |
| automatically. |
| |
| At some point LibVNCServer may implement a "rfbFBCrop" pseudoencoding |
| that viewers can use to learn which portion of the framebuffer to |
| actually show to the users (with the hidden part used for caching, or |
| perhaps something else, maybe double buffering or other offscreen |
| rendering...) |
| |
| The Enhanced TightVNC Viewer (SSVNC) Unix viewer has a nice -ycrop |
| option to help hide the pixel cache area from view. It will turn on |
| automatically if the framebuffer appears to be very tall (height more |
| than twice the width), or you can supply the actual value for the |
| height. If the screen is resized by scaling, etc, the ycrop value is |
| scaled as well. In fullscreen mode you cannot scroll past the end of |
| the actual screen, and in non-fullscreen mode the window manager frame |
| is adjusted to fit the actual display (so you don't see the pixel |
| cache region) and the scrollbars are very thin to avoid distraction |
| and trouble fitting inside your display. Use the "-sbwidth n" viewer |
| option to make the scrollbars thicker if you like. |
| |
| Another drawback of the scheme is that it is VERY memory intensive, |
| the n in "-ncache n" is the factor of increase over the base |
| framebuffer size to use for caching. It is an even integer and should |
| be fairly large, 6-12, to achieve good response. This usually requires |
| about 50-100MB of additional RAM on both the client and server sides. |
| For example with n=6 a 1280x1024 display will use a framebuffer that |
| is 1280x7168: everything below row 1024 is the pixel buffer cache. If |
| you are running on low memory machines or memory is tight because of |
| other running applications you should not use -ncache. |
| |
| The reason for so much memory is because the pixel data is not |
| compressed and so the whole window to be saved must be stored |
| "offscreen". E.g. for a large web browser window this can be nearly 1 |
| million pixels, and that is only for a single window! One typically |
| wants to cycle between 5-10 large active windows. Also because both |
| backing-store (the window's actual contents) and save-unders (the |
| pixels covered up by the window) are cached offscreen that introduces |
| an additional factor of 2 in memory use. |
| |
| However, even in the smallest usage mode with n equal 2 and |
| -ncache_no_rootpixmap set (this requires only 2X additional |
| framebuffer memory) there is still a noticable improvement for many |
| activities, although it is not as dramatic as with, say n equal 12 and |
| rootpixmap (desktop background) caching enabled. |
| |
| The large memory consumption of the current implementation can be |
| thought of as a tradeoff to providing caching and being compatible |
| with all VNC viewers and also ease of implementing. Hopefully it can |
| be tuned to use less, or the VNC community will extend the protocol to |
| allow caching and replaying of compressed blobs of data. |
| |
| Another option to experiment with is "-ncache_cr". By specifying it, |
| x11vnc will try to do smooth opaque window moves instead of its |
| wireframe. This can give a very nice effect (note: on Unix the realvnc |
| viewer seems to be smoother than the tightvnc viewer), but can lead to |
| some painting problems, and can be jerky in some circumstances. |
| |
| Surprisingly, for very slow connections, e.g. modem, the -ncache_cr |
| option can actually improve window drags. This is probably because no |
| pixel data (only CopyRect instructions) are sent when dragging a |
| window. Normally, the wireframe must be sent and this involves |
| compressing and sending the lines that give rise to the moving box |
| effect (note that real framebuffer data is sent to "erase" the white |
| lines of the box.) |
| |
| If you experience painting errors you can can tap the Alt_L key (Left |
| "Alt" key) 3 times in a row to signal x11vnc to refresh the screen to |
| all viewers. You may also need to iconify and then deiconify any |
| damaged windows to correct their cache data as well. Note that if you |
| change color viewer depth (e.g. 8bpp to full color) dynamically that |
| will usually lead to the entire extended framebuffer being resent |
| which can take a long time over very slow links: it may be better to |
| reconnect and reset the format right after doing so. x11vnc will try |
| to detect the format change and clear (make completely black) the |
| cache region. |
| |
| Gotcha for older Unix VNC Viewers: The older Unix VNC viewers (e.g. |
| current TightVNC Unix Viewer) require X server backingstore to keep |
| off-viewer screen data local. If the viewer-side X server has |
| backingstore disabled (sadly, currently the default on Linux, etc), |
| then to get the offscreen pixels the viewer has to ask for a refresh |
| over the network, thereby defeating the caching. Use something like |
| this in your viewer-side /etc/X11/xorg.conf file (or otherwise get |
| your viewer-side system to do it) |
| Section "Device" |
| ... |
| Option "backingstore" |
| ... |
| EndSection |
| |
| No problems like this have been observed with Windows VNC Viewers: |
| they all seem to keep their entire framebuffer in local memory. |
| |
| Gotcha for KDE krdc VNC Viewer: One user found that KDE's krdc viewer |
| has some sort of hardwired limit on the maximum size of the |
| framebuffer (64MB?). It fails quickly saying "The connection to the |
| host has been interrupted." The workaround for his 1280x1024 |
| x11vnc-side display was to run with "-ncache 10", i.e. a smaller value |
| to be under the krdc threshold. |
| |
| Although this scheme is not as quick (nor as compressed) as |
| nx/nomachine, say, it does provide a good step in the direction of |
| improving VNC performance by client side caching. |
| |
| |
| Q-80: Does x11vnc support TurboVNC? |
| |
| As of Feb/2009 (development tarball) there is an experimental kludge |
| to let you build x11vnc using TurboVNC's modified TightVNC encoding. |
| TurboVNC is part of the VirtualGL project. It does two main things to |
| speed up the TightVNC encoding: |
| * It eliminates bottlenecks, overheads, wait-times in the TightVNC |
| encoding implementation and instead only worries about sending |
| very well (and quickly) compressed JPEG data. |
| * A fast proprietary JPEG implemention is used (Intel IPP on x86) |
| instead of the usual libjpeg implementation. TurboJPEG is an |
| interface library, libturbojpeg, provided by the project that |
| achieves this. |
| |
| TurboVNC works very well over LAN and evidently fast Broadband too. |
| When using it with x11vnc in such a situation you may want to dial |
| down the delays, e.g. "-wait 5" and "-defer 5" (or even a smaller |
| setting) to poll and pump things out more quickly. |
| |
| See the instructions in "x11vnc/misc/turbovnc/README" for how to build |
| x11vnc with TurboVNC support. You will also need to download the |
| TurboJPEG software. |
| |
| In brief, the steps look like this: |
| cd x11vnc-x.y.z/x11vnc/misc/turbovnc |
| ./apply_turbovnc |
| cd ../../.. |
| env LDFLAGS='-L/DIR -Xlinker --rpath=/DIR' ./configure |
| make AM_LDFLAGS='-lturbojpeg' |
| |
| where you replace "/DIR" with the directory containing libturbojpeg.so |
| you downloaded separately. If it works out well enough TurboVNC |
| support will be integrated into x11vnc and more of its tuning features |
| will be implemented. Support for TurboVNC in SSVNC viewer has been |
| added as an experiment as well. If you try either one, let us know how |
| it went. |
| |
| There also may be some Linux.i686 and Darwin.i386 x11vnc binaries with |
| TurboVNC support in the misc. bins directory. For other platforms you |
| will need to compile yourself. |
| |
| On relatively cheap and old hardware (Althon64 X2 5000+ / GeForce |
| 6200) x11vnc and SSVNC, both TurboVNC enabled, were able to sustain |
| 13.5 frames/sec (fps) and 15 Megapixels/sec using the VirtualGL |
| supplied OpenGL benchmark program glxspheres. VirtualGL on higher-end |
| hardware can sustain 20-30 fps with the glxspheres benchmark. |
| |
| Potential Slowdown: As we describe elsewhere, unless you use x11vnc |
| with an X server using, say, NVidia proprietary drivers (or a virtual |
| X server like Xvfb or Xdummy, or in ShadowFB mode), then the read rate |
| from the graphics card can be rather slow (e.g. 10 MB/sec) and becomes |
| the bottleneck when using x11vnc over fast networks. Note that all of |
| Xorg's drivers currently (2009) have slow read rates (only proprietary |
| drivers appear to have optimized reads.) |
| |
| So under these (more or less typical) conditions, the speed |
| improvement provided by TurboVNC may only be marginal. Look for this |
| output to see your read rate: |
| 28/02/2009 11:11:07 Autoprobing TCP port |
| 28/02/2009 11:11:07 Autoprobing selected port 5900 |
| 28/02/2009 11:11:08 fb read rate: 10 MB/sec |
| 28/02/2009 11:11:08 screen setup finished. |
| |
| A rate of 10 MB/sec means a 1280x1024x24 screen takes 0.5 seconds to |
| read in. TurboVNC compresses that to JPEG in a much shorter time. On |
| the other hand, an NVidia driver may have a read rate of 250 MB/sec |
| and so only takes 0.02 seconds to read the entire screen in. |
| |
| |
| |
| [Mouse Cursor Shapes] |
| |
| Q-81: Why isn't the mouse cursor shape (the little icon shape where |
| the mouse pointer is) correct as I move from window to window? |
| |
| On X servers supporting XFIXES or Solaris/IRIX Overlay extensions it |
| is possible for x11vnc to do this correctly. See a few paragraphs down |
| for the answer. |
| |
| Historically, the X11 mouse cursor shape (i.e. little picture: an |
| arrow, X, I-beam, resizer, etc) is one of the few WRITE-only objects |
| in X11. That is, an application can tell the X server what the cursor |
| shape should be when the pointer is in a given window, but a program |
| (like x11vnc) unfortunately cannot read this information. I believe |
| this is because the cursor shape is often downloaded to the graphics |
| hardware (video card), but I could be mistaken. |
| |
| A simple kludge is provided by the "-cursor X" option that changes the |
| cursor when the mouse is on the root background (or any window has the |
| same cursor as the root background.) Note that desktops like GNOME or |
| KDE often cover up the root background, so this won't work for those |
| cases. Also see the "-cursor some" option for additional kludges. |
| |
| Note that as of Aug/2004 on Solaris using the SUN_OVL overlay |
| extension and IRIX, x11vnc can show the correct mouse cursor when the |
| -overlay option is supplied. See this FAQ for more info. |
| |
| Also as of Dec/2004 XFIXES X extension support has been added to allow |
| exact extraction of the mouse cursor shape. XFIXES fixes the problem |
| of the cursor-shape being write-only: x11vnc can now query the X |
| server for the current shape and send it back to the connected |
| viewers. XFIXES is available on recent Linux Xorg based distros and |
| Solaris 10. |
| |
| The only XFIXES issue is the handling of alpha channel transparency in |
| cursors. If a cursor has any translucency then in general it must be |
| approximated to opaque RGB values for use in VNC. There are some |
| situations where the cursor transparency can also handled exactly: |
| when the VNC Viewer requires the cursor shape be drawn into the VNC |
| framebuffer or if you apply a patch to your VNC Viewer to extract |
| hidden alpha channel data under 32bpp. Details can be found here. |
| |
| |
| Q-82: When using XFIXES cursorshape mode, some of the cursors look |
| really bad with extra black borders around the cursor and other cruft. |
| How can I improve their appearance? |
| |
| This happens for cursors with transparency ("alpha channel"); regular |
| X cursors (bitmaps) should be correct. Unfortunately x11vnc 0.7 was |
| released with a very poor algorithm for approximating the |
| transparency, which led to the ugly black borders. |
| |
| The problem is as follows: XFIXES allows x11vnc to retrieve the |
| current X server cursor shape, including the alpha channel for |
| transparency. For traditional bitmap cursors the alpha value will be 0 |
| for completely transparent pixels and 255 for completely opaque |
| pixels; whereas for modern, eye-candy cursors an alpha value between 0 |
| and 255 means to blend in the background colors to that degree with |
| the cursor colors. The pixel color blending formula is something like |
| this: Red = Red_cursor * a + Red_background * (1 - a), (where here 0 |
| =< a =< 1), with similar for Green and Blue. The VNC protocol does not |
| currently support an alpha channel in cursors: it only supports |
| regular X bitmap cursors and Rich Cursors that have RGB (Red, Green, |
| Blue) color data, but no "A" = alpha data. So in general x11vnc has to |
| approximate a cursor with transparency to create a Rich Cursor. This |
| is easier said than done: some cursor themes have cursors with |
| complicated drop shadows and other forms of translucency. |
| |
| Anyway, for the x11vnc 0.7.1 release the algorithm for approximating |
| transparency is much improved and hopefully gives decent cursor shapes |
| for most cursor themes and you don't have to worry about it. |
| |
| In case it still looks bad for your cursor theme, there are (of |
| course!) some tunable parameters. The "-alphacut n" option lets you |
| set the threshold "n" (between 0 and 255): cursor pixels with alpha |
| values below n will be considered completely transparent while values |
| equal to or above n will be completely opaque. The default is 240. The |
| "-alphafrac f" option tries to correct individual cursors that did not |
| fare well with the default -alphacut value: if a cursor has less than |
| fraction f (between 0.0 and 1.0) of its pixels selected by the default |
| -alphacut, the threshold is lowered until f of its pixels are |
| selected. The default fraction is 0.33. |
| |
| Finally, there is an option -alpharemove that is useful for themes |
| where many cursors are light colored (e.g. "whiteglass".) XFIXES |
| returns the cursor data with the RGB values pre-multiplied by the |
| alpha value. If the white cursors look too grey, specify -alpharemove |
| to brighten them by having x11vnc divide out the alpha value. |
| |
| One user played with these parameters and reported back: |
| Of the cursor themes present on my system: |
| |
| gentoo and gentoo-blue: alphacut:192 - noalpharemove |
| |
| gentoo-silver: alphacut:127 and alpharemove |
| |
| whiteglass and redglass (presumably also handhelds, which is based |
| heavily on redglass) look fine with the apparent default of alphacut:255. |
| |
| |
| Q-83: In XFIXES mode, are there any hacks to handle cursor |
| transparency ("alpha channel") exactly? |
| |
| As of Jan/2005 libvncserver has been modified to allow an alpha |
| channel (i.e. RGBA data) for Rich Cursors. So x11vnc can now send the |
| alpha channel data to libvncserver. However, this data will only be |
| used for VNC clients that do not support the CursorShapeUpdates VNC |
| extension (or have disabled it.) It can be disabled for all clients |
| with the -nocursorshape x11vnc option. In this case the cursor is |
| drawn, correctly blended with the background, into the VNC framebuffer |
| before being sent out to the client. So the alpha blending is done on |
| the x11vnc side. Use the -noalphablend option to disable this behavior |
| (always approximate transparent cursors with opaque RGB values.) |
| |
| The CursorShapeUpdates VNC extension complicates matters because the |
| cursor shape is sent to the VNC viewers supporting it, and the viewers |
| draw the cursor locally. This improves response over slow links. Alpha |
| channel data for these locally drawn cursors is not supported by the |
| VNC protocol. |
| |
| However, in the libvncserver CVS there is a patch to the TightVNC |
| viewer to make this work for CursorShapeUpdates under some |
| circumstances. This hack is outside of the VNC protocol. It requires |
| the screens on both sides to be depth 24 at 32bpp (it uses the extra 8 |
| bits to secretly hide the cursor alpha channel data.) Not only does it |
| require depth 24 at 32bpp, but it also currently requires the client |
| and server to be of the same endianness (otherwise the hidden alpha |
| data gets reset to zero by a libvncserver translation function; we can |
| fix this at some point if there is interest.) The patch is for the |
| TightVNC 1.3dev5 Unix vncviewer and it enables the TightVNC viewer to |
| do the cursor alpha blending locally. The patch code should give an |
| example on how to change the Windows TightVNC viewer to achieve the |
| same thing (send me the patch if you get that working.) |
| |
| This patch is applied to the Enhanced TightVNC Viewer (SSVNC) package |
| we provide. |
| |
| [Mouse Pointer] |
| |
| Q-84: Why does the mouse arrow just stay in one corner in my |
| vncviewer, whereas my cursor (that does move) is just a dot? |
| |
| This default takes advantage of a tightvnc extension |
| (CursorShapeUpdates) that allows specifying a cursor image shape for |
| the local VNC viewer. You may disable it with the -nocursor option to |
| x11vnc if your viewer does not have this extension. |
| |
| Note: as of Aug/2004 this should be fixed: the default for |
| non-tightvnc viewers (or ones that do not support CursorShapeUpdates) |
| will be to draw the moving cursor into the x11vnc framebuffer. This |
| can also be disabled via -nocursor. |
| |
| |
| Q-85: Can I take advantage of the TightVNC extension to the VNC |
| protocol where Cursor Positions Updates are sent back to all connected |
| clients (i.e. passive viewers can see the mouse cursor being moved |
| around by another viewer)? |
| |
| Use the -cursorpos option when starting x11vnc. A VNC viewer must |
| support the Cursor Positions Updates for the user to see the mouse |
| motions (the TightVNC viewers support this.) As of Aug/2004 -cursorpos |
| is the default. See also -nocursorpos and -nocursorshape. |
| |
| |
| Q-86: Is it possible to swap the mouse buttons (e.g. left-handed |
| operation), or arbitrarily remap them? How about mapping button clicks |
| to keystrokes, e.g. to partially emulate Mouse wheel scrolling? |
| |
| You can remap the mouse buttons via something like: -buttonmap 13-31 |
| (or perhaps 12-21.) Also, note that xmodmap(1) lets you directly |
| adjust the X server's button mappings, but in some circumstances it |
| might be more desirable to have x11vnc do it. |
| |
| One user had an X server with only one mouse button(!) and was able to |
| map all of the VNC client mouse buttons to it via: -buttonmap 123-111. |
| |
| Note that the -debug_pointer option prints out much info for every |
| mouse/pointer event and is handy in solving problems. |
| |
| To map mouse button clicks to keystrokes you can use the alternate |
| format where the keystrokes are enclosed between colons like this |
| :<KeySym>: in place of the mouse button digit. For a sequence of |
| keysyms separate them with "+" signs. Look in the include file |
| <X11/keysymdef.h>, or use xev(1), or -debug_keyboard to find the |
| keysym names. Button clicks can also be included in the sequence via |
| the fake keysyms Button1, etc. |
| |
| As an example, suppose the VNC viewer machine has a mouse wheel (these |
| generate button 4 and 5 events), but the machine that x11vnc is run on |
| only has the 3 regular buttons. In normal operation x11vnc will |
| discard the button 4 and 5 events. However, either of the following |
| button maps could possibly be of use emulating the mouse wheel events |
| in this case: |
| -buttonmap 12345-123:Prior::Next: |
| -buttonmap 12345-123:Up+Up+Up::Down+Down+Down: |
| |
| Exactly what keystroke "scrolling" events they should be bound to |
| depends on one's taste. If this method is too approximate, one could |
| consider not using -buttonmap but rather configuring the X server to |
| think it has a mouse with 5 buttons even though the physical mouse |
| does not. (e.g. 'Option "ZAxisMapping" "4 5"'.) |
| |
| Note that when a keysym-mapped mouse button is clicked down this |
| immediately generates the key-press and key-release events (for each |
| keysym in turn if the mapping has a sequence of keysyms.) When the |
| mouse button goes back up nothing is generated. |
| |
| If you include modifier keys like Shift_L instead of key-press |
| immediately followed by key-release the state of the modifier key is |
| toggled (however the initial state of the modifier key is ignored.) So |
| to map the right button to type my name 'Karl Runge' I could use this: |
| -buttonmap 3-:Shift_L+k+Shift_L+a+r+l+space+Shift_L+r+Shift_L+u+n+g+e: |
| |
| (yes, this is getting a little silly.) |
| |
| BTW, Coming the other way around, if the machine you are sitting at |
| does not have a mouse wheel, but the remote machine does (or at least |
| has 5 buttons configured), this key remapping can be useful: |
| -remap Super_R-Button4,Menu-Button5 |
| |
| you just tap those two keys to get the mouse wheel scrolls (this is |
| more useful than the Up and Down arrow keys because a mouse wheel |
| "click" usually gives a multi-line scroll.) |
| [Keyboard Issues] |
| |
| Q-87: How can I get my AltGr and Shift modifiers to work between |
| keyboards for different languages? |
| |
| The option -modtweak should help here. It is a mode that monitors the |
| state of the Shift and AltGr Modifiers and tries to deduce the correct |
| keycode to send, possibly by sending fake modifier key presses and |
| releases in addition to the actual keystroke. |
| |
| Update: As of Jul/2004 -modtweak is now the default (use -nomodtweak |
| to get the old behavior.) This was done because it was noticed on |
| newer XFree86 setups even on bland "us" keyboards like "pc104 us" |
| XFree86 included a "ghost" key with both "<" and ">" it. This key does |
| not exist on the keyboard (see this FAQ for more info.) Without |
| -modtweak there was then an ambiguity in the reverse map keysym => |
| keycode, making it so the "<" symbol could not be typed. |
| |
| Also see the FAQ about the -xkb option for a more powerful method of |
| modifier tweaking for use on X servers with the XKEYBOARD extension. |
| |
| When trying to resolve keyboard mapping problems, note that the |
| -debug_keyboard option prints out much info for every keystroke and so |
| can be useful debugging things. |
| |
| Note that one user had a strange setup and none of the above helped. |
| His solution was to disable all of the above and use -nomodtweak. This |
| is the simplest form of keystroke insertion and it actually solved the |
| problem. Try it if the other options don't help. |
| |
| |
| Q-88: When I try to type a "<" (i.e. less than) instead I get ">" |
| (i.e. greater than)! Strangely, typing ">" works OK!! |
| |
| Does your keyboard have a single key with both "<" and ">" on it? Even |
| if it doesn't, your X server may think your keyboard has such a key |
| (e.g. pc105 in the XF86Config file when it should be something else, |
| say pc104.) |
| |
| Short Cut: Try the -xkb or -sloppy_keys options and see if that helps |
| the situation. The discussion below is a bit outdated (e.g. -modtweak |
| is now the default) but it is useful reference for various tricks and |
| so is kept. |
| |
| |
| The problem here is that on the Xserver where x11vnc is run there are |
| two keycodes that correspond to the "<" keysym. Run something like |
| this to see: |
| |
| xmodmap -pk | egrep -i 'KeyCode|less|greater' |
| There are 4 KeySyms per KeyCode; KeyCodes range from 8 to 255. |
| KeyCode Keysym (Keysym) ... |
| 59 0x002c (comma) 0x003c (less) |
| 60 0x002e (period) 0x003e (greater) |
| 94 0x003c (less) 0x003e (greater) |
| |
| That keycode 94 is the special key with both "<" and ">". When x11vnc |
| receives the "<" keysym over the wire from the remote VNC client, it |
| unfortunately maps it to keycode 94 instead of 59, and sends 94 to the |
| X server. Since Shift is down (i.e. you are Shifting the comma key), |
| the X server interprets this as Shifted-94, which is ">". |
| |
| A workaround in the X server configuration is to "deaden" that special |
| key: |
| |
| xmodmap -e "keycode 94 = " |
| |
| However, one user said he had to do this: |
| |
| xmodmap -e "keycode 94 = 0x002c 0x003c" |
| |
| (If the numerical values are different for your setup, substitute the |
| ones that correspond to your display. The above xmodmap scheme can |
| often be used to work around other ambiguous keysym to keycode |
| mappings.) |
| |
| Alternatively, here are some x11vnc options to try to work around the |
| problem: |
| -modtweak |
| |
| and |
| -remap less-comma |
| |
| These are convenient in that they do not modify the actual X server |
| settings. The former (-modtweak) is a mode that monitors the state of |
| the Shift and AltGr modifiers and tries to deduce the correct keycode |
| sequence to send. Since Jul/2004 -modtweak is now the default. The |
| latter (-remap less-comma) is an immediate remapping of the keysym |
| less to the keysym comma when it comes in from a client (so when Shift |
| is down the comma press will yield "<".) |
| |
| See also the FAQ about the -xkb option as a possible workaround using |
| the XKEYBOARD extension. |
| |
| Note that the -debug_keyboard option prints out much info for every |
| keystroke to aid debugging keyboard problems. |
| |
| |
| Q-89: Extra Character Inserted, E.g.: When I try to type a "<" (i.e. |
| less than) instead I get "<," (i.e. an extra comma.) |
| |
| This is likely because you press "Shift" then "<" but then released |
| the Shift key before releasing the "<". Because of a keymapping |
| ambiguity the last event "< up" is interpreted as "," because that key |
| unshifted is the comma. |
| |
| This extra character insertion will happen for other combinations of |
| characters: in general it can happen whenever the Shift key is |
| released early. |
| |
| This should not happen in -xkb mode, because it works hard to resolve |
| the ambiguities. If you do not want to use -xkb, try the option |
| -sloppy_keys to attempt a similar type of algorithm. |
| |
| One user had this problem for Italian and German keyboards with the |
| key containing ":" and "." When he typed ":" he would get an extra "." |
| inserted after the ":". The solution was -sloppy_keys. |
| |
| |
| Q-90: I'm using an "international" keyboard (e.g. German "de", or |
| Danish "dk") and the -modtweak mode works well if the VNC viewer is |
| run on a Unix/Linux machine with a similar keyboard. But if I run |
| the VNC viewer on Unix/Linux with a different keyboard (e.g. "us") or |
| Windows with any keyboard, I can't type some keys like: "@", "$", |
| "<", ">", etc. How can I fix this? |
| |
| The problem with Windows is it does not seem to handle AltGr well. It |
| seems to fake it up by sending Control_L+Alt_R to applications. The |
| Windows VNC viewer sends those two down keystrokes out on the wire to |
| the VNC server, but when the user types the next key to get, e.g., "@" |
| the Windows VNC viewer sends events bringing the up the |
| Control_L+Alt_R keys, and then sends the "@" keysym by itself. |
| |
| The Unix/Linux VNC viewer on a "us" keyboard does a similar thing |
| since "@" is the Shift of the "2" key. The keysyms Shift and "@" are |
| sent to the VNC server. |
| |
| In both cases no AltGr is sent to the VNC server, but we know AltGr is |
| needed on the physical international keyboard to type a "@". |
| |
| This all worked fine with x11vnc running with the -modtweak option (it |
| figures out how to adjust the Modifier keys (Shift or AltGr) to get |
| the "@".) However it fails under recent versions of XFree86 (and the |
| X.org fork.) These run the XKEYBOARD extension by default and make |
| heavy use of it to handle international keyboards. |
| |
| To make a long story short, on these newer XFree86 setups the |
| traditional X keymap lookup x11vnc uses is no longer accurate. x11vnc |
| can't find the keysym "@" anywhere in the keymapping! (even though it |
| is in the XKEYBOARD extended keymapping.) |
| |
| How to Solve: As of Jul/2004 x11vnc has two changes: |
| * -modtweak (tweak Modifier keys) is now the default (use |
| -nomodtweak to go back to the old way) |
| * there is a new option -xkb to use the XKEYBOARD extension API to |
| do the Modifier key tweaking. |
| |
| The -xkb option seems to fix all of the missing keys: "@", "<", ">", |
| etc.: it is recommended that you try it if you have this sort of |
| problem. Let us know if there are any remaining problems (see the next |
| paragraph for some known problems.) If you specify the -debug_keyboard |
| (aka -dk) option twice you will get a huge amount of keystroke |
| debugging output (send it along with any problems you report.) |
| |
| Update: as of Jun/2005 x11vnc will try to automatically enable -xkb if |
| it appears that would be beneficial (e.g. if it sees any of "@", "<", |
| ">", "[" and similar keys are mapped in a way that needs the -xkb to |
| access them.) To disable this automatic check use -noxkb. |
| |
| Known problems: |
| * One user had to disable a "ghost" Mode_switch key that was causing |
| problems under -xkb. His physical AltGr key was bound to |
| ISO_Level3_Shift (which seems to be the XKEYBOARD way of doing |
| things), while there was a ghost key Mode_switch (which seems to |
| be obsolete) in the mapping as well. Both of these keysyms were |
| bound to Mod5 and x11vnc was unfortunately choosing Mode_switch. |
| From the x11vnc -xkb -dk -dk output it was noted that Mode_switch |
| was attached to keycode 93 (no physical key generates this |
| keycode) while ISO_Level3_Shift was attached to keycode 113. The |
| keycode skipping option was used to disable the ghost key: |
| -skip_keycodes 93 |
| * In implementing -xkb we noticed that some characters were still |
| not getting through, e.g. "~" and "^". This is not really an |
| XKEYBOARD problem. What was happening was the VNC viewer was |
| sending the keysyms asciitilde and asciicircum to x11vnc, but on |
| the X server with the international keyboard those keysyms were |
| not mapped to any keys. So x11vnc had to skip them (Note: as of |
| May/2005 they are added by default see -add_keysyms below.) |
| The way these characters are typically entered on international |
| keyboards is by "dead" (aka "mute") keys. E.g. to enter "~" at the |
| physical display the keysym dead_tilde is pressed and released |
| (this usually involves holding AltGr down while another key is |
| pressed) and then space is pressed. (this can also be used get |
| characters with the "~" symbol on top, e.g. "ã" by typing "a" |
| instead of space.) |
| What to do? In general the VNC protocol has not really solved this |
| problem: what should be done if the VNC viewer sends a keysym not |
| recognized by the VNC server side? Workarounds can possibly be |
| created using the -remap x11vnc option: |
| -remap asciitilde-dead_tilde,asciicircum-dead_circumflex |
| etc. Use -remap filename if the list is long. Please send us your |
| workarounds for this problem on your keyboard. Perhaps we can have |
| x11vnc adjust automatically at some point. Also see the |
| -add_keysyms option in the next paragraph. |
| Update: for convenience "-remap DEAD" does many of these mappings |
| at once. |
| * To complement the above workaround using the -remap, an option |
| -add_keysyms was added. This option instructs x11vnc to bind any |
| unknown Keysyms coming in from VNC viewers to unused Keycodes in |
| the X server. This modifies the global state of the X server. When |
| x11vnc exits it removes the extra keymappings it created. Note |
| that the -remap mappings are applied first, right when the Keysym |
| is received from a VNC viewer, and only after that would |
| -add_keysyms, or anything else, come into play. |
| Update: -add_keysyms is now on by default. Use -noadd_keysyms to |
| disable. |
| |
| |
| Q-91: When typing I sometimes get double, triple, or more of my |
| keystrokes repeated. I'm sure I only typed them once, what can I do? |
| |
| This may be due to an interplay between your X server's key autorepeat |
| delay and the extra time delays caused by x11vnc processing. |
| |
| Short answer: disable key autorepeating by running the command "xset r |
| off" on the Xserver where x11vnc is run (restore via "xset r on") or |
| use the new (Jul/2004) -norepeat x11vnc option. You will still have |
| autorepeating because that is taken care of on your VNC viewer side. |
| |
| Update: as of Dec/2004 -norepeat is now the default. Use -repeat to |
| disable it. |
| |
| Details: |
| suppose you press a key DOWN and it generates changes in large regions |
| of the screen. The CPU and I/O work x11vnc does for the large screen |
| change could be longer than your X server's key autorepeat delay. |
| x11vnc may not get to processing the key UP event until after the |
| screen work is completed. The X server believes the key has been held |
| down all this time, and applies its autorepeat rules. |
| |
| Even without inducing changes in large regions of the screen, this |
| problem could arise when accessing x11vnc via a dialup modem or |
| otherwise high latency link (e.g. > 250 ms latency.) |
| |
| Look at the output of "xset q" for the "auto repeat delay" setting. Is |
| it low (e.g. < 300 ms)? If you turn off autorepeat completely: "xset r |
| off", does the problem go away? |
| |
| The workaround is to manually apply "xset r off" and "xset r on" as |
| needed, or to use the -norepeat (which has since Dec/2004 been made |
| the default.) Note that with X server autorepeat turned off the VNC |
| viewer side of the connection will (nearly always) do its own |
| autorepeating so there is no big loss here, unless someone is also |
| working at the physical display and misses his autorepeating. |
| |
| |
| Q-92: The x11vnc -norepeat mode is in effect, but I still get repeated |
| keystrokes!! |
| |
| Are you using x11vnc to log in to an X session via display manager? |
| (as described in this FAQ) If so, x11vnc is starting before your |
| session and it disables autorepeat when you connect, but then after |
| you log in your session startup (GNOME, KDE, ...) could be resetting |
| the autorepeat to be on. Or it could be something inside your desktop |
| trying to be helpful that decides to turn it back on. |
| |
| x11vnc in -norepeat mode will by default reset autorepeat to off 2 |
| times (to help get thru the session startup problem), but it will not |
| continue to battle with things turning autorepeat back on. It will |
| also turn autorepeat off whenever it goes from a state of zero clients |
| to one client. You can adjust the number of resets via "-norepeat N", |
| or use "-norepeat -1" to have it keep resetting it whenever autorepeat |
| gets turned back on when clients are connected. |
| |
| In general you can manually turn autorepeating off by typing "xset r |
| off", or a using desktop utility/menu, or "x11vnc -R norepeat". If |
| something in your desktop is automatically turning it back on you |
| should figure out how to disable that somehow. |
| |
| |
| Q-93: After using x11vnc for a while, I find that I cannot type some |
| (or any) characters or my mouse clicks and drags no longer have any |
| effect, or they lead to strange effects. What happened? |
| |
| Probably a modifier key, e.g. Control or Alt is "stuck" in a pressed |
| down state. |
| |
| This happens for VNC in general by the following mechanism. Suppose on |
| the Viewer side desktop there is some hot-key to switch |
| desktops/rooms/spaces, etc. E.g. suppose Alt+LeftArrow moves to the |
| left desktop/room/space. Or suppose an Alt+hotkey combination |
| iconifies a window. This can leave the Alt key pressed down on the |
| remote side. |
| |
| Consider the sequence that happens. The Alt_L key and then the |
| LeftArrow key go down. Since you are inside the viewer the Alt_L key |
| press is sent to the other side (x11vnc) and so it is pressed down in |
| the remote desktop as well. (by "Alt_L" we mean the Alt key on the |
| left-hand side of the keyboard.) Your local desktop (where the VNC |
| Viewer is running) then warps to the new desktop/room/space: Leaving |
| the Alt_L key still pressed down in the remote desktop. |
| |
| If someone is sitting at the desktop, or when you return in the viewer |
| it may be very confusing because the Alt_L is still pressed down but |
| you (or the person sitting at the desktop) do not realize this. |
| Depending on which remote desktop (x11vnc side) is used, it can act |
| very strangely. |
| |
| A quick workaround when you notice this is to press and release all of |
| the Alt, Shift, Control, Windows-Flag, modifier keys to free the |
| pressed one. You need to do this for both the left and right Shift, |
| Alt, Control, etc. keys to be sure. |
| |
| Note that many VNC Viewers try to guard against this when they are |
| notified by the window system that the viewer app has "lost focus". |
| When it receives the "lost focus" event, the viewer sends VNC |
| Key-Release events for all modifier keys that are currently pressed |
| down. This does not always work, however, since it depends on how the |
| desktop manages these "warps". If the viewer is not notified it cannot |
| know it needs to release the modifiers. |
| |
| You can also use the -clear_mods option to try to clear all of the |
| modifier keys at x11vnc startup. You will still have to be careful |
| that you do not leave the modifier key pressed down during your |
| session. It is difficult to prevent this problem from occurring (short |
| of using -remap to prevent sending all of the problem modifier keys, |
| which would make the destkop pretty unusable.) |
| |
| During a session these x11vnc remote control commands can also help: |
| x11vnc -R clear_mods |
| x11vnc -R clear_keys |
| x11vnc -R clear_locks |
| x11vnc -R clear_all |
| |
| A similar problem can occur if you accidentally press the Caps_Lock or |
| Num_Lock down. When these are locked on the remote side it can |
| sometimes lead to strange desktop behavior (e.g. cannot drag or click |
| on windows.) As above you may not notice this because the lock isn't |
| down on the local (Viewer) side. See this FAQ on lock keys problem. |
| These options may help avoid the problem: -skip_lockkeys and |
| -capslock. See also -clear_all. |
| |
| |
| Q-94: The machine where I run x11vnc has an AltGr key, but the local |
| machine where I run the VNC viewer does not. Is there a way I can map |
| a local unused key to send an AltGr? How about a Compose key as well? |
| |
| Something like "-remap Super_R-Mode_switch" x11vnc option may work. |
| Note that Super_R is the "Right Windoze(tm) Flaggie" key; you may want |
| to choose another. The -debug_keyboard option comes in handy in |
| finding keysym names (so does xev(1).) |
| |
| For Compose how about "-remap Menu-Multi_key" (note that Multi_key is |
| the official name for Compose.) To do both at the same time: "-remap |
| Super_R-Mode_switch,Menu-Multi_key" or use "-remap filename" to |
| specify remappings from a file. |
| |
| |
| Q-95: I have a Sun machine I run x11vnc on. Its Sun keyboard has just |
| one Alt key labelled "Alt" and two Meta keys labelled with little |
| diamonds. The machine where I run the VNC viewer only has Alt keys. |
| How can I send a Meta keypress? (e.g. emacs needs this) |
| |
| Here are a couple ideas. The first one is to simply use xmodmap(1) to |
| adjust the Sun X server. Perhaps xmodmap -e "keysym Alt_L = Meta_L |
| Alt_L" will do the trick. (there are other ways to do it, one user |
| used: xmodmap -e "keycode 26 = Meta_L" for his setup.) |
| |
| Since xmodmap(1) modifies the X server mappings you may not want to do |
| this (because it affects local work on that machine.) Something like |
| the -remap Alt_L-Meta_L to x11vnc may be sufficient for ones needs, |
| and does not modify the X server environment. Note that you cannot |
| send Alt_L in this case, maybe -remap Super_L-Meta_L would be a better |
| choice if the Super_L key is typically unused in Unix. |
| |
| |
| Q-96: Running x11vnc on HP-UX I cannot type "#" I just get a "3" |
| instead. |
| |
| One user reports this problem on HP-UX Rel_B.11.23. The problem was |
| traced to a strange keyboard mapping for the machine (e.g. xmodmap -pk |
| output) that looked like: |
| ... |
| 039 2 at at at |
| ... |
| 047 3 numbersign numbersign numbersign |
| |
| and similar triple mappings (with two in the AltGr/Mode_switch group) |
| of a keysum to a single keycode. |
| |
| Use the -nomodtweak option as a workaround. You can also use xmodmap |
| to correct these mappings in the server, e.g.: |
| xmodmap -e "keycode 47 = 3 numbersign" |
| |
| Also, as of Feb/2007, set the environment variable MODTWEAK_LOWEST=1 |
| (either in your shell or via "-env MODTWEAK_LOWEST=1" option) to |
| handle these mappings better. |
| |
| |
| Q-97: Can I map a keystroke to a mouse button click on the remote |
| machine? |
| |
| This can be done directly in some X servers using AccessX and |
| Pointer_EnableKeys, but is a bit awkward. It may be more convenient to |
| have x11vnc do the remapping. This can be done via the -remap option |
| using the fake "keysyms" Button1, Button2, etc. as the "to" keys (i.e. |
| the ones after the "-") |
| |
| As an example, consider a laptop where the VNC viewer is run that has |
| a touchpad with only two buttons. It is difficult to do a middle |
| button "paste" because (using XFree86/Xorg Emulate3Buttons) you have |
| to click both buttons on the touch pad at the same time. This |
| remapping: |
| -remap Super_R-Button2 |
| |
| maps the Super_R "flag" key press to the Button2 click, thereby making |
| X pasting a bit easier. |
| |
| Note that once the key goes down, the button down and button up events |
| are generated immediately on the x11vnc side. When the key is released |
| (i.e. goes up) no events are generated. |
| |
| Q-98: How can I get Caps_Lock to work between my VNC viewer and |
| x11vnc? |
| |
| This is a little tricky because it is possible to get the Caps_Lock |
| state out of sync between your viewer-side machine and the x11vnc-side |
| X server. For best results, we recommend not ever letting the |
| Caps_Lock keypresses be processed by x11vnc. That way when you press |
| Caps_Lock in the viewer your local machine goes into the Caps_Lock on |
| state and sends keysym "A" say when you press "a". x11vnc will then |
| fake things up so that Shift is held down to generate "A". The |
| -skip_lockkeys option should help to accomplish this. For finer grain |
| control use something like: "-remap Caps_Lock-None". |
| |
| Also try the -nomodtweak and -capslock options. |
| |
| Another useful option that turns off any Lock keys on the remote side |
| at startup and end is the -clear_all option. During a session you can |
| run these remote control commands to modify the Lock keys: |
| x11vnc -R clear_locks |
| x11vnc -R clear_all |
| |
| the former will try to unset any Lock keys, the latter will do same |
| and also try to make it so no key is pressed down (e.g. "stuck" Alt_L, |
| etc.) |
| [Screen Related Issues and Features] |
| |
| Q-99: The remote display is larger (in number of pixels) than the |
| local display I am running the vncviewer on. I don't like the |
| vncviewer scrollbars, what I can do? |
| |
| vncviewer has a option (usually accessible via F8 key or -fullscreen |
| option) for vncviewer to run in full screen, where it will |
| automatically scroll when the mouse is near the edge of the current |
| view. For quick scrolling, also make sure Backing Store is enabled on |
| the machine vncviewer is run on. (XFree86/Xorg disables it by default |
| for some reason, add Option "backingstore" to XF86Config on the |
| vncviewer side.) |
| |
| BTW, contact me if you are having problems with vncviewer in |
| fullscreen mode with your window manager (i.e. no keyboard response.) |
| I have a workaround for vncviewer using XGrabServer(). |
| |
| There may also be scaling viewers out there (e.g. TightVNC or UltraVNC |
| on Windows) that automatically shrink or expand the remote framebuffer |
| to fit the local display. Especially for hand-held devices. See also |
| the next FAQ on x11vnc scaling. |
| |
| |
| Q-100: Does x11vnc support server-side framebuffer scaling? (E.g. to |
| make the desktop smaller.) |
| |
| As of Jun/2004 x11vnc provides basic server-side scaling. It is a |
| global scaling of the desktop, not a per-client setting. To enable it |
| use the "-scale fraction" option. "fraction" can either be a floating |
| point number (e.g. -scale 0.75) or the alternative m/n fraction |
| notation (e.g. -scale 3/4.) Note that if fraction is greater than one |
| the display is magnified. |
| |
| Extra resources (CPU, memory I/O, and memory) are required to do the |
| scaling. If the machine is slow where x11vnc is run with scaling |
| enabled, the interactive response can be unacceptable. OTOH, if run |
| with scaling on a fast machine the performance degradation is usually |
| not a big issue or even noticeable. |
| |
| It may help to compile x11vnc with compiler option -O3 or -O4 to speed |
| up the scaling code. Set the CFLAGS env. var. before running |
| configure. |
| |
| Also, if you just want a quick, rough "thumbnail" of the display you |
| can append ":nb" to the fraction to turn on "no blending" mode. E.g.: |
| "-scale 1/3:nb" Fonts will be difficult to read, but the larger |
| features will be recognizable. BTW, "no blending" mode is forced on |
| when scaling 8bpp PseudoColor displays (because blending an indexed |
| colormap is a bad idea and leads to random colors, use :fb to force it |
| on.) |
| |
| One can also use the ":nb" with an integer scale factor (say "-scale |
| 2:nb") to use x11vnc as a screen magnifier for vision impaired |
| applications. Since with integer scale factors the framebuffers become |
| huge and scaling operations time consuming, be sure to use ":nb" for |
| the fastest response. |
| |
| In general for a scaled display if you are using a TightVNC viewer you |
| may want to turn off jpeg encoding (e.g. vncviewer -nojpeg host:0.) |
| There appears to be a noise enhancement effect, especially for regions |
| containing font/text: the scaling can introduce some pixel artifacts |
| that evidently causes the tight encoding algorithm to incorrectly |
| detect the regions as image data and thereby introduce additional |
| pixel artifacts due to the lossiness of the jpeg compression |
| algorithm. Experiment to see if -nojpeg vncviewer option improves the |
| readability of text when using -scale to shrink the display size. Also |
| note that scaling may actually slow down the transfer of text regions |
| because after being scaled they do not compress as well. (this can |
| often be a significant slowdown, e.g. 10X.) |
| |
| Another issue is that it appears VNC viewers require the screen width |
| to be a multiple of 4. When scaling x11vnc will round the width to the |
| nearest multiple of 4. To disable this use the ":n4" sub option (like |
| ":nb" in the previous paragraph; to specify both use a comma: |
| ":nb,n4", etc.) |
| |
| If one desires per-client scaling for something like 1:1 from a |
| workstation and 1:2 from a smaller device (e.g. handheld), currently |
| the only option is to run two (or more) x11vnc processes with |
| different scalings listening on separate ports (-rfbport option, etc.) |
| |
| Update: As of May/2006 x11vnc also supports the UltraVNC server-side |
| scaling. This is a per-client scaling by factors 1/2, 1/3, ... and so |
| may be useful for PDA's ("-scale 1/2", etc. will give similar results |
| except that it applies to all clients.) You may need to supply |
| "-rfbversion 3.6" for this to be recognized by UltraVNC viewers. |
| |
| BTW, whenever you run two or more x11vnc's on the same X display and |
| use the GUI, then to avoid all of the x11vnc's simultaneously |
| answering the gui you will need to use something like "-connect file1 |
| -gui ..." with different connect files for each x11vnc you want to |
| control via the gui (or remote-control.) The "-connect file1" usage |
| gives separate communication channels between a x11vnc process and the |
| gui process. Otherwise they all share the same X property channels: |
| VNC_CONNECT and X11VNC_REMOTE. |
| |
| Update: As of Mar/2005 x11vnc now scales the mouse cursor with the |
| same scale factor as the screen. If you don't want that, use the |
| "-scale_cursor frac" option to set the cursor scaling to a different |
| factor (e.g. use "-scale_cursor 1" to keep the cursor at its natural |
| unscaled size.) |
| |
| |
| Q-101: Does x11vnc work with Xinerama? (i.e. multiple monitors joined |
| together to form one big, single screen.) |
| |
| Yes, it should generally work because it simply polls the big |
| effective screen. |
| |
| If the viewing-end monitor is not as big as the remote Xinerama |
| display, then the vncviewer scrollbars, etc, will have to be used to |
| pan across the large area. However one user started two x11vnc's, one |
| with "-clip 1280x1024+0+0" and the other with "-clip 1280x1024+1280+0" |
| to split the big screen into two and used two VNC viewers to access |
| them. |
| |
| As of Jun/2008: Use "-clip xinerama0" to clip to the first xinerama |
| sub-screen (if xinerama is active.) xinerama1 for the 2nd sub-screen, |
| etc. This way you don't need to figure out the WxH+X+Y of the desired |
| xinerama sub-screen. screens are sorted in increasing distance from |
| the (0,0) origin (I.e. not the Xserver's order.) |
| |
| There are a couple potential issues with Xinerama however. If the |
| screen is not rectangular (e.g. 1280x1024 and 1024x768 monitors joined |
| together), then there will be "non-existent" areas on the screen. The |
| X server will return "garbage" image data for these areas and so they |
| may be distracting to the viewer. The -blackout x11vnc option allows |
| you to blacken-out rectangles by manually specifying their WxH+X+Y |
| geometries. If your system has the libXinerama library, the -xinerama |
| x11vnc option can be used to have it automatically determine the |
| rectangles to be blackened out. (Note on 8bpp PseudoColor displays the |
| fill color may not be black.) Update: -xinerama is now on by default. |
| |
| Some users have reported that the mouse does not behave properly for |
| their Xinerama display: i.e. the mouse cannot be moved to all regions |
| of the large display. If this happens try using the -xwarppointer |
| option. This instructs x11vnc to fake mouse pointer motions using the |
| XWarpPointer function instead of the XTestFakeMotionEvent XTEST |
| function. (This may be due to a bug in the X server for XTEST when |
| Xinerama is enabled.) Update: As of Dec/2006 -xwarppointer will be |
| applied automatically if Xinerama is detected. To disable use: |
| -noxwarppointer |
| |
| |
| Q-102: Can I use x11vnc on a multi-headed display that is not Xinerama |
| (i.e. separate screens :0.0, :0.1, ... for each monitor)? |
| |
| You can, but it is a little bit awkward: you must start separate |
| x11vnc processes for each screen, and on the viewing end start up |
| separate VNC viewer processes connecting to them. e.g. on the remote |
| end: |
| x11vnc -display :0.0 -bg -q -rfbport 5900 |
| x11vnc -display :0.1 -bg -q -rfbport 5901 |
| |
| (this could be automated in the display manager Xsetup for example) |
| and then on the local machine where you are sitting: |
| vncviewer somehost:0 & |
| vncviewer somehost:1 & |
| |
| Note: if you are running on Solaris 8 or earlier you can easily hit up |
| against the maximum of 6 shm segments per process (for Xsun in this |
| case) from running multiple x11vnc processes. You should modify |
| /etc/system as mentioned in another FAQ to increase the limit. It is |
| probably also a good idea to run with the -onetile option in this case |
| (to limit each x11vnc to 3 shm segments), or even -noshm to use no shm |
| segments. |
| |
| |
| Q-103: Can x11vnc show only a portion of the display? (E.g. for a |
| special purpose application or a very large screen.) |
| |
| As of Mar/2005 x11vnc has the "-clip WxH+X+Y" option to select a |
| rectangle of width W, height H and offset (X, Y). Thus the VNC screen |
| will be the clipped sub-region of the display and be only WxH in size. |
| One user used -clip to split up a large Xinerama screen into two more |
| managable smaller screens. |
| |
| This also works to view a sub-region of a single application window if |
| the -id or -sid options are used. The offset is measured from the |
| upper left corner of the selected window. |
| |
| |
| Q-104: Does x11vnc support the XRANDR (X Resize, Rotate and |
| Reflection) extension? Whenever I rotate or resize the screen x11vnc |
| just seems to crash. |
| |
| As of Dec/2004 x11vnc supports XRANDR. You enable it with the -xrandr |
| option to make x11vnc monitor XRANDR events and also trap X server |
| errors if the screen change occurred in the middle of an X call like |
| XGetImage. Once it traps the screen change it will create a new |
| framebuffer using the new screen. |
| |
| If the connected vnc viewers support the NewFBSize VNC extension |
| (Windows TightVNC viewer and RealVNC 4.0 windows and Unix viewers do) |
| then the viewer will automatically resize. Otherwise, the new |
| framebuffer is fit as best as possible into the original viewer size |
| (portions of the screen may be clipped, unused, etc.) For these |
| viewers you can try the -padgeom option to make the region big enough |
| to hold all resizes and rotations. We have fixed this problem for the |
| TightVNC Viewer on Unix: SSVNC |
| |
| If you specify "-xrandr newfbsize" then vnc viewers that do not |
| support NewFBSize will be disconnected before the resize. If you |
| specify "-xrandr exit" then all will be disconnected and x11vnc will |
| terminate. |
| |
| |
| Q-105: Independent of any XRANDR, can I have x11vnc rotate and/or |
| reflect the screen that the VNC viewers see? (e.g. for a handheld |
| whose screen is rotated 90 degrees.) |
| |
| As of Jul/2006 there is the -rotate option allow this. E.g's: "-rotate |
| +90", "-rotate -90", "-rotate x", etc. |
| |
| |
| Q-106: Why is the view in my VNC viewer completely black? Or why is |
| everything flashing around randomly? |
| |
| See the next FAQ for a possible explanation. |
| |
| |
| Q-107: I use Linux Virtual Terminals (VT's) to implement 'Fast User |
| Switching' between users' sessions (e.g. Betty is on Ctrl-Alt-F7, |
| Bobby is on Ctrl-Alt-F8, and Sid is on Ctrl-Alt-F1: they use those |
| keystrokes to switch between their sessions.) How come the view in a |
| VNC viewer connecting to x11vnc is either completely black or |
| otherwise all messed up unless the X session x11vnc is attached to is |
| in the active VT? |
| |
| This seems to have to do with how applications (the X server processes |
| in this case) must "play nicely" if they are not on the active VT |
| (sometimes called VC for virtual console.) That is, they should not |
| read from the keyboard or mouse or manage the video display unless |
| they have the active VT. Given that it appears the XGetImage() call |
| must ultimately retrieve the framebuffer data from the video hardware |
| itself, it would make sense x11vnc's polling wouldn't work unless the |
| X session had active control of the VT. |
| |
| There does not seem to be an easy way to work around this. Even xwd(1) |
| doesn't work in this case (try it.) Something would need to be done at |
| a lower level, say in the XFree86/Xorg X server. Also, using the |
| Shadow Framebuffer (a copy of the video framebuffer is kept in main |
| memory) does not appear to fix the problem. |
| |
| If no one is sitting at the workstation and you just want to remotely |
| switch the VT over to the one associated with your X session (so |
| x11vnc can poll it correctly), one can use the chvt(1) command, e.g. |
| "chvt 7" for VT #7. |
| |
| |
| Q-108: I am using x11vnc where my local machine has "popup/hidden |
| taskbars" and the remote display where x11vnc runs also has |
| "popup/hidden taskbars" and they interfere and fight with each other. |
| What can I do? |
| |
| When you move the mouse to the edge of the screen where the popups |
| happen, the taskbars interfere with each other in strange ways. This |
| sometimes happens where the local machine is GNOME or Mac OS X and the |
| remote machine is GNOME. Is there a way to temporarily disable one or |
| both of these magic desktop taskbars? |
| |
| One x11vnc user suggests: it should be straightforward to right mouse |
| click on the task bar panel, and uncheck "enable auto-hide" from the |
| panel properties dialog box. This will make the panel always visible. |
| |
| Q-109: Help! x11vnc and my KDE screensaver keep switching each other |
| on and off every few seconds. |
| |
| This is a new (Jul/2006) problem seen, say, on the version of KDE that |
| is shipped with SuSE 10.1. It is not yet clear what is causing this... |
| If you move the mouse through x11vnc the screensaver shuts off like it |
| should but then a second or two after you stop moving the mouse the |
| screensaver snaps back on. |
| |
| This may be a bug in kdesktop_lock. For now the only workaround is to |
| disable the screensaver. You can try using another one such as |
| straight xscreensaver (see the instructions here for how to disable |
| kdesktop_lock.) If you have more info on this or see it outside of KDE |
| please let us know. |
| |
| Update: It appears this is due to kdesktop_lock enabling the screen |
| saver when the Monitor is in DPMS low-power state (e.g. standby, |
| suspend, or off.) In Nov/2006 the x11vnc -nodpms option was added as a |
| workaround. Normally it is a good thing that the monitor powers down |
| (since x11vnc can still poll the framebuffer in this state), but if |
| you experience the kdesktop_lock problem you can specify the "-nodpms" |
| option to keep the Monitor out of low power state while VNC clients |
| are connected. This is basically the same as typing "xset dpms force |
| on" periodically. (if you don't want to do these things just disable |
| the screensaver.) Feel free to file a bug against kdesktop_lock with |
| KDE. |
| |
| Q-110: I am running the compiz 3D window manager (or beryl, MythTv, |
| Google Earth, or some other OpenGL app) and I do not get screen |
| updates in x11vnc. |
| |
| This appears to be because the 3D OpenGL/GLX hardware screen updates |
| do not get reported via the XDAMAGE mechanism. So this is a bug in |
| compiz/beryl or XDAMAGE/Xorg or the (possibly 3rd party) video card |
| driver. |
| |
| As a workaround apply the -noxdamage option. As of Feb/2007 x11vnc |
| will try to autodetect the problem and disable XDAMAGE if is appears |
| to be missing a lot of updates. But if you know you are using compiz |
| you might as well always supply -noxdamage. Thanks to this user who |
| reported the problem and discovered the workaround. |
| |
| A developer for MiniMyth reports that the 'alphapulse' tag of the |
| theme G.A.N.T. can also cause problems, and should be avoided when |
| using VNC. |
| |
| Please report a bug or complaint to Beryl/Compiz and/or Xorg about |
| this: running x11vnc with -noxdamage disables a nice improvement in |
| responsiveness (especially for typing) and also leads to unnecessary |
| CPU and memory I/O load due to the extra polling. |
| |
| Update: as of May/2010 NVIDIA may have fixed this problem in their |
| proprietary drivers. See the NVIDIA Release Notes. (look for |
| 'x11vnc'.) |
| |
| Q-111: Can I use x11vnc to view my VMWare session remotely? |
| |
| Yes, since VMWare usually runs as an X application you can view it via |
| x11vnc in the normal way. |
| |
| Note that VMWare has several viewing modes: |
| * Normal X application window (with window manager frame) |
| * Quick-Switch mode (with no window manager frame) |
| * Fullscreen mode |
| |
| The way VMWare does Fullscreen mode on Linux is to display the Guest |
| desktop in a separate Virtual Terminal (e.g. VT 8) (see this FAQ on |
| VT's for background.) Unfortunately, this Fullscreen VT is not an X |
| server. So x11vnc cannot access it (however, see this discussion of |
| -rawfb for a possible workaround.) x11vnc works fine with "Normal X |
| application window" and "Quick-Switch mode" because these use X. |
| |
| Update: It appears the in VMWare 5.x the Fullscreen mode is X, so |
| x11vnc access does work. |
| |
| One user reports he left his machine with VMWare in the Fullscreen |
| mode, and even though his X session wasn't in the active VT, he could |
| still connect x11vnc to the X session and pass the keystrokes Ctrl-Alt |
| (typing "blind") to the VMWare X app. This induced VMWare to switch |
| out of Fullscreen into Normal X mode and he could continue working in |
| the Guest desktop remotely. |
| |
| |
| Aside: Sometimes it is convenient (for performance, etc.) to start |
| VMWare in its own X session using startx(1). This can be used to have |
| a minimal window manger (e.g. twm or even no window manager), to |
| improve response. One can also cut the display depth (e.g. to 16bpp) |
| in this 2nd X session to improve video performance. This 2nd X session |
| emulates Fullscreen mode to some degree and can be viewed via x11vnc |
| as long as the VMWare X session is in the active VT. |
| |
| Also note that with a little bit of playing with "xwininfo -all |
| -children" output one can extract the (non-toplevel) window-id of the |
| of the Guest desktop only when VMWare is running as a normal X |
| application. Then one can export just the guest desktop (i.e. without |
| the VMWare menu buttons) by use of the -id windowid option. The |
| caveats are the X session VMWare is in must be in the active VT and |
| the window must be fully visible, so this mode is not terribly |
| convenient, but could be useful in some circumstances (e.g. running |
| VMWare on a very powerful server machine in a server room that happens |
| to have a video card, (but need not have a monitor, Keyboard or |
| mouse).) |
| |
| |
| |
| [Exporting non-X11 devices via VNC] |
| |
| Q-112: Can non-X devices (e.g. a raw framebuffer) be viewed (and even |
| controlled) via VNC with x11vnc? |
| |
| As of Apr/2005 there is support for this. Two options were added: |
| "-rawfb string" (to indicate the raw frame buffer device, file, etc. |
| and its parameters) and "-pipeinput command" (to provide an external |
| program that will inject or otherwise process mouse and keystroke |
| input.) Some useful -pipeinput schemes, VID, CONSOLE, and UINPUT, have |
| since been built into x11vnc for convenience. |
| |
| This non-X mode for x11vnc is somewhat experimental because it is so |
| removed in scope from the intended usage of the tool. Incomplete |
| attempt is made to make all of the other options consistent with non-X |
| framebuffer polling. So all of the X-related options (e.g. |
| -add_keysyms, -xkb) are just ignored or may cause an error if used. Be |
| careful applying such an option via remote control. |
| |
| The format for the -rawfb string is: |
| -rawfb <type>:<object>@<W>x<H>x<bpp>[-<BPL>][:<R>/<G>/<B>][+<offset>] |
| |
| There are also some useful aliases (e.g. "console".) Some examples: |
| -rawfb shm:210337933@800x600x32:ff/ff00/ff0000 |
| |
| -rawfb map:/dev/fb0@1024x768x16 |
| |
| -rawfb map:/tmp/Xvfb_screen0@640x480x8+3232 |
| |
| -rawfb file:/tmp/my.pnm@250x200x24+37 |
| |
| -rawfb file:/dev/urandom@128x128x8 |
| |
| -rawfb snap:/dev/video0@320x240x24 -24to32 |
| |
| -rawfb console |
| |
| -rawfb vt2 |
| |
| -rawfb video |
| |
| -rawfb setup:mycmd.sh |
| |
| So the type can be "shm" for shared memory objects, and "map" or |
| "file" for file objects. "map" uses mmap(2) to map the file into |
| memory and is preferred over "file" (that uses the slower lseek(2) |
| access method.) Only use file if map isn't working. BTW, "mmap" is an |
| alias for "map" and if you do not supply a type and the file exists, |
| map is assumed (see the -help output and below for some exceptions to |
| this.) The "snap:" setting applies the -snapfb option with "file:" |
| type reading (this is useful for exporting webcams or TV tuner video; |
| see the next FAQ for more info.) |
| |
| Also, if the string is of the form "setup:cmd" then cmd is run and the |
| first line of its output retrieved and used as the rawfb string. This |
| allows initializing the device, determining WxHxB, etc. |
| |
| The object will be the numerical shared memory id for the case of shm. |
| The idea here is some other program has created this shared memory |
| segment and periodically updates it with new framebuffer data. x11vnc |
| polls the area for changes. See shmat(2) and ipcs(8) for more info. |
| The ipcs command will list current shared memory segments on the |
| system. Sometimes you can snoop on a program's framebuffer it did not |
| expect you would be polling! |
| |
| The object will be the path to the regular or character special file |
| for the cases of map and file. The idea here is that in the case of a |
| regular file some other program is writing/updating framebuffer image |
| data to it. In the case of a character special (e.g. /dev/fb0) it is |
| the kernel that is "updating" the framebuffer data. |
| |
| In most cases x11vnc needs to be told the width, height, and number of |
| bits per pixel (bpp) of the framebuffer. This is the @WxHxB field. For |
| the case of the Linux framebuffer device, /dev/fb0, the fbset(8) may |
| be of use (but may not always be accurate for what is currently |
| viewable.) In general some guessing may be required, especially for |
| the bpp. Update: in "-rawfb console" mode x11vnc will use the linuxfb |
| API to try to guess (it is still not always accurate.) Also try |
| "-rawfb vtN" (on x11vnc 0.9.7 and later) for the N-th Linux text |
| console (aka virtual terminal.) If the number of Bytes Per Line is not |
| WxHxB/8 (i.e. the framebuffer lines are padded) you can specify this |
| information after WxHxB via "-BPL", e.g. @800x600x16-2048 |
| |
| Based on the bpp x11vnc will try to guess the red, green, and blue |
| masks (these indicate which bits correspond to each color.) It if gets |
| it wrong you can specify them manually via the optional ":R/G/B" |
| field. E.g. ":0xff0000/0x00ff00/0x0000ff" (this is the default for |
| 32bpp.) |
| |
| Finally, the framebuffer may not begin at the beginning of the memory |
| object, so use the optional "+offset" parameter to indicate where the |
| framebuffer information starts. So as an example, the Xvfb virtual |
| framebuffer has options -shmem and -fbdir for exporting its virtual |
| screen to either shm or a mapped file. The format of these is XWD and |
| so the initial header should be skipped. BTW, since XWD is not |
| strictly RGB the view will only be approximate, but usable. Of course |
| for the case of Xvfb x11vnc can poll it much better via the X API, but |
| you get the idea. |
| |
| By default in -rawfb mode x11vnc will actually close any X display it |
| happened to open. This is basically to shake out bugs (e.g it will |
| crash rather than mysteriously interacting with the X display.) If you |
| want x11vnc to keep the X display open while polling the raw |
| framebuffer prefix a "+" sign at the beginning of the string (e.g. |
| +file:/dev/urandom@64x64x8) This could be convenient for keeping the |
| remote control channel active (it uses X properties.) The "-connect |
| /path/to/file" mechanism could also be used for remote control to |
| avoid the X property channel. Rare usage, but if you also supply |
| -noviewonly in this "+" mode then the mouse and keyboard input are |
| still sent to the X display, presumably for doing something amusing |
| with /dev/fb... |
| |
| Interesting Devices:. Here are some aliases for interesting device |
| files that can be polled via -rawfb: |
| -rawfb console /dev/fb0 Linux Console |
| -rawfb vt2 /dev/vcsa2 Linux Console (e.g. virtual ter |
| minal #2) |
| -rawfb video /dev/video0 Video4Linux Capture device |
| -rawfb rand /dev/urandom Random Bytes |
| -rawfb null /dev/zero Zero Bytes (black screen) |
| |
| The Linux console, /dev/fb0, etc needs to have its driver enabled in |
| the kernel. Some of the drivers are video card specific and |
| accelerated. The console is either the Text consoles (usually |
| tty1-tty6), or X graphical display (usually starting at tty7.) In |
| addition to the text console other graphical ones may be viewed and |
| interacted with as well, e.g. DirectFB or SVGAlib apps, VMWare non-X |
| fullscreen, or Qt-embedded apps (PDAs/Handhelds.) By default the |
| pipeinput mechanisms UINPUT and CONSOLE (keystrokes only) are |
| automatically attempted in this mode under "-rawfb console". |
| |
| The Video4Linux Capture device, /dev/video0, etc is either a Webcam or |
| a TV capture device and needs to have its driver enabled in the |
| kernel. See this FAQ for details. If specified via "-rawfb Video" then |
| the pipeinput method "VID" is applied (it lets you change video |
| parameters dynamically via keystrokes.) |
| |
| The last two, /dev/urandom and /dev/zero are just for fun, but are |
| also useful in testing. |
| |
| |
| All of the above -rawfb options are just for viewing the raw |
| framebuffer (although some of the aliases do imply keystroke and mouse |
| pipeinput methods.) That may be enough for certain applications of |
| this feature (e.g. suppose a video camera mapped its framebuffer into |
| memory and you just wanted to look at it via VNC.) |
| To handle the pointer and keyboard input from the viewer users the |
| "-pipeinput cmd" option was added to indicate a helper program to |
| process the user input. The input is streamed to it and looks |
| something like this: |
| Pointer 1 205 257 0 None |
| Pointer 1 198 253 0 None |
| Pointer 1 198 253 1 ButtonPress-1 |
| Pointer 1 198 253 0 ButtonRelease-1 |
| Pointer 1 198 252 0 None |
| Keysym 1 1 119 w KeyPress |
| Keysym 1 0 119 w KeyRelease |
| Keysym 1 1 65288 BackSpace KeyPress |
| Keysym 1 0 65288 BackSpace KeyRelease |
| Keysym 1 1 112 p KeyPress |
| Keysym 1 0 112 p KeyRelease |
| |
| Run "-pipeinput tee:/bin/cat" to get a description of the format. Note |
| that the -pipeinput option is independent of -rawfb mode and so may |
| have some other interesting uses. The "tee:" prefix means x11vnc will |
| both process the user input and pipe it to the command. The default is |
| to just pipe it to the -pipeinput command. |
| |
| Note the -pipeinput helper program could actually control the raw |
| framebuffer. In the libvncserver CVS a simple example program |
| x11vnc/misc/slide.pl is provided that demonstrates a simple jpeg |
| "slideshow" application. Also the builtin "-pipeinput VID" mode does |
| this for webcams and TV capture devices (/dev/video0.) |
| |
| The -pipeinput program is run with these environment variables set: |
| X11VNC_PID, X11VNC_PROG, X11VNC_CMDLINE, X11VNC_RAWFB_STR to aid its |
| knowing what is up. |
| |
| Another example provided in libvncserver CVS is a script to inject |
| keystrokes into the Linux console (e.g. the virtual consoles: |
| /dev/tty1, /dev/tty2, etc) in x11vnc/misc/vcinject.pl. It is based on |
| the vncterm/LinuxVNC.c program also in the libvncserver CVS. So to |
| view and interact with VT #2 (assuming it is the active VT) one can |
| run something like: |
| x11vnc -rawfb map:/dev/fb0@1024x768x16 -pipeinput './vcinject.pl 2' |
| |
| This assumes your Linux framebuffer device (/dev/fb0) is properly |
| configured. See fbset(8) and other documentation. Try |
| "file:/dev/fb0@WxHxB" as a last resort. Starting with x11vnc 0.8.1, |
| the above VT injection is built in, as well as WxHxB determination. |
| Just use something like: |
| x11vnc -rawfb console |
| |
| this will try to guess the active virtual console (via /dev/tty0) and |
| also the /dev/fb0 WxHxB and rgb masks automatically. Use, e.g., |
| "-rawfb console3" to force the VT number. This input method can be |
| used generally via "-pipeinput CONSOLE". Also starting with x11vnc |
| 0.8.2 the "-pipeinput UINPUT" mode is tried first (it does both |
| keyboard and mouse input) and then falls back to CONSOLE mode if it is |
| not available. Here is the -help output for this mode: |
| |
| If the rawfb string begins with "console" the framebuffer device |
| /dev/fb0 is opened (this requires the appropriate kernel modules to |
| be installed) and so is /dev/tty0. The latter is used to inject |
| keystrokes (not all are supported, but the basic ones are.) You |
| will need to be root to inject keystrokes. /dev/tty0 refers to the |
| active VT, to indicate one explicitly, use "console2", etc. using |
| the VT number. |
| |
| If the Linux version seems to be 2.6 or later and the "uinput" |
| module appears to be present, then the uinput method will be used |
| instead of /dev/ttyN. uinput allows insertion of BOTH keystrokes |
| and mouse input and so it preferred when accessing graphical (e.g. |
| Qt-embedded) linux console apps. See -pipeinput UINPUT below for |
| more information on this mode (you may want to also use the |
| -nodragging and -cursor none options.) Use "console0", etc or |
| -pipeinput CONSOLE to force the /dev/ttyN method. |
| |
| Note you can change VT remotely using the chvt(1) command. |
| Sometimes switching out and back corrects the framebuffer state. |
| |
| To skip input injecting entirely use "consolex". |
| |
| The string "/dev/fb0" (1, etc) can be used instead of "console". |
| This can be used to specify a different framebuffer device, e.g. |
| /dev/fb1. As a shortcut the "/dev/" can be dropped. If the name is |
| something nonstandard, use "console:/dev/foofb" |
| |
| If you do not want x11vnc to guess the framebuffer's WxHxB and |
| masks automatically (sometimes the kernel gives inaccurate |
| information), specify them with a @WxHxB at the end of the string. |
| |
| The above is just an example of what can be done. Note that if you |
| really want to view and interact with the Linux Text console it is |
| better to use the more accurate and faster LinuxVNC program. The |
| advantage x11vnc -rawfb might have is that it can allow interaction |
| with a non-text application, e.g. one based on SVGAlib or Qt-embedded |
| Also, for example the VMWare Fullscreen mode is actually viewable |
| under -rawfb and can be interacted with if uinput is enabled. |
| |
| If the Linux uinput driver is available then full keystroke and mouse |
| input into the Linux console can be performed. You may be able to |
| enable uinput via commands like these: |
| modprobe uinput |
| mknod /dev/input/uinput c 10 223 |
| |
| The -rawfb and -pipeinput features are intended to help one creatively |
| "get out of a jam" (say on a legacy or embedded device) where X is |
| absent or doesn't work properly. Feedback and bug reports are welcome. |
| For more control and less overhead use libvncserver in your own C |
| program that passes the framebuffer to libvncserver. |
| |
| |
| Q-113: Can I export the Linux Console (Virtual Terminals) via VNC |
| using x11vnc? |
| |
| Yes, you may need to be root to access the devices that make up the |
| linux console. |
| |
| To access the active Linux console via the computer's framebuffer try |
| something like: |
| x11vnc -rawfb console |
| x11vnc -rawfb console2 |
| |
| These will try to access the framebuffer through /dev/fb (or /dev/fb0, |
| etc.) and if it succeeds it will show any text or graphics that is |
| currently displayed. Keystrokes will be injected via the device |
| /dev/tty0 (to force an explicit virtual terminal append a number, e.g. |
| "console2" to select /dev/tty2.) |
| |
| If your Linux system does not have a framebuffer device (/dev/fb) you |
| can get one by adding, e.g., vga=0x31B boot parameter. This enables |
| the VGA framebuffer device at 1280x1024x24. 0x317 gives 1024x768x16, |
| etc. You can also enable a Linux framebuffer device by modprobing a |
| framebuffer driver specific to your video card. |
| |
| Note that this "-rawfb console" mode shows the contents of the |
| hardware framebuffer, and so will show whatever is on the screen. It |
| has no concept of Virtual Terminals WRT what there is to view, it |
| always shows the active virtual terminal. |
| |
| Another mode is specific to the Linux text Virtual Terminals, it shows |
| their text and colors (but no graphics) regardless of whether it is |
| the active VT or not. It is available on x11vnc 0.9.7 and later. |
| Enable this mode like this: |
| x11vnc -rawfb vt |
| x11vnc -rawfb vt2 |
| |
| The former will select the active one, the latter the 2nd VT. x11vnc |
| implements this mode by opening the current console text file |
| "/dev/vcsa2" instead of "/dev/fb". In this way it provides the basic |
| functionality of the LibVNCServer LinuxVNC program. |
| |
| The vt mode can be a useful way to try to get a machine's X server |
| working remotely, e.g. you edit /etc/X11/xorg.conf and then type |
| startx (or similar, e.g. gdm) in the virtual terminal. A 2nd x11vnc |
| could be used to see if the X server is now working correctly. |
| |
| Q-114: Can I export via VNC a Webcam or TV tuner framebuffer using |
| x11vnc? |
| |
| Yes, this is possible to some degree with the -rawfb option. There is |
| no X11 involved: snapshots from the video capture device are used for |
| the screen image data. See the previous FAQ on -rawfb for background. |
| For best results, use x11vnc version 0.8.1 or later. |
| |
| Roughly, one would do something like this: |
| x11vnc -rawfb snap:/dev/video@320x240x32 |
| |
| This requires that the system allows simple read(2) access to the |
| video device. This is true for video4Linux on Linux kernel 2.6 and |
| later (it won't work for 2.4, you'll need a separate program to |
| snapshot to a file that you point -rawfb to; ask me if it is not clear |
| what to do.) |
| |
| The "snap:" enforces -snapfb mode which appears to be necessary. The |
| read pointer for video capture devices cannot be repositioned (which |
| would be needed for scanline polling), but you can read a full frame |
| of data from the device. |
| |
| On Linux, if the Video4Linux API is present or the v4l-info(1) program |
| (related to xawtv) exists in in PATH, then x11vnc can be instructed to |
| try it to determine the -rawfb WxHxB parameters for you automatically. |
| In this case one would just type: |
| x11vnc -rawfb video |
| |
| or "-rawfb video1" for the 2nd video device, etc. |
| |
| x11vnc has also been extended to use the Video4Linux API over v4l-info |
| if it is available at build time. This enables setting parameters |
| (e.g. size and brightness) via x11vnc. See the description below. |
| Without Video4Linux you will need to initialize the settings of the |
| video device using something like xawtv or spcaview (and then hope the |
| settings persist until x11vnc reopens the device.) |
| |
| Many video4linux drivers tend to set the framebuffer to be 24bpp (as |
| opposed to 32bpp.) Since this can cause problems with VNC viewers, |
| etc, the -24to32 option will be automatically imposed when in 24bpp. |
| |
| Note that by its very nature, video capture involves rapid change in |
| the framebuffer. This is especially true for cameras where slight |
| wavering in brightness is always happening. This can lead to much |
| network bandwidth consumption for the VNC traffic and also local CPU |
| and I/O resource usage. You may want to experiment with "dialing down" |
| the framerate via the -wait, -slow_fb, or -defer options. Decreasing |
| the window size and bpp also helps. |
| |
| |
| Setting Camera/Tuner parameters via x11vnc: |
| |
| There is also some support for setting parameters of the capture |
| device. This is done via "-rawfb video:<settings>". This could be |
| useful for unattended startup at boottime, etc. Here is the -help |
| description: |
| |
| A more sophisticated video device scheme allows initializing the |
| device's settings using: |
| |
| -rawfb video:<settings> |
| |
| The prefix could also be, as above, e.g. "video1:" to specify the |
| device file. The v4l API must be available for this to work. |
| Otherwise, you will need to try to initialize the device with an |
| external program, e.g. xawtv, spcaview, and hope they persist when |
| x11vnc re-opens the device. |
| |
| <settings> is a comma separated list of key=value pairs. The |
| device's brightness, color, contrast, and hue can be set to |
| percentages, e.g. br=80,co=50,cn=44,hu=60. |
| |
| The device filename can be set too if needed (if it does not start |
| with "video"), e.g. fn=/dev/qcam. |
| |
| The width, height and bpp of the framebuffer can be set via, e.g., |
| w=160,h=120,bpp=16. |
| |
| Related to the bpp above, the pixel format can be set via the |
| fmt=XXX, where XXX can be one of: GREY, HI240, RGB555, RGB565, |
| RGB24, and RGB32 (with bpp 8, 8, 16, 16, 24, and 32 respectively.) |
| See http://www.linuxtv.org for more info (V4L api.) |
| |
| For TV/rf tuner cards one can set the tuning mode via tun=XXX where |
| XXX can be one of PAL, NTSC, SECAM, or AUTO. |
| |
| One can switch the input channel by the inp=XXX setting, where XXX |
| is the name of the input channel (Television, Composite1, S-Video, |
| etc.) Use the name that is in the information about the device that |
| is printed at startup. |
| |
| For input channels with tuners (e.g. Television) one can change |
| which station is selected by the sta=XXX setting. XXX is the |
| station number. Currently only the ntsc-cable-us (US cable) |
| channels are built into x11vnc. See the -freqtab option below to |
| supply one from xawtv. If XXX is greater than 500, then it is |
| interpreted as a raw frequency in KHz. |
| |
| Example: |
| |
| -rawfb video:br=80,w=320,h=240,fmt=RGB32,tun=NTSC,sta=47 |
| |
| one might need to add inp=Television too for the input channel to |
| be TV if the card doesn't come up by default in that one. |
| |
| Note that not all video capture devices will support all of the |
| above settings. |
| |
| See the -pipeinput VID option below for a way to control the |
| settings through the VNC Viewer via keystrokes. |
| |
| As above, if you specify a "@WxHxB..." after the <settings> string |
| they are used verbatim: the device is not queried for the current |
| values. Otherwise the device will be queried. |
| |
| Also, if you supply the "-pipeinput VID" (or use "-rawfb Video") |
| option you can control the settings to some degree via keystroke |
| mappings, e.g. B to increase the brightness or Up arrow to change the |
| TV station: |
| |
| For "-pipeinput VID" and you are using the -rawfb for a video |
| capture device, then an internal list of keyboard mappings is used |
| to set parameters of the video. The mappings are: |
| |
| "B" and "b" adjust the brightness up and down. |
| "H" and "h" adjust the hue. |
| "C" and "c" adjust the colour. |
| "N" and "n" adjust the contrast. |
| "S" and "s" adjust the size of the capture screen. |
| "I" and "i" cycle through input channels. |
| Up and Down arrows adjust the station (if a tuner) |
| F1, F2, ..., F6 will switch the video capture pixel |
| format to HI240, RGB565, RGB24, RGB32, RGB555, and |
| GREY respectively. See -rawfb video for details. |
| |
| See also the -freqtab option to supply your own xawtv channel to |
| frequency mappings for your country (only ntsc-cable-us is built into |
| x11vnc.) |
| |
| |
| Q-115: Can I connect via VNC to a Qt-embedded/Qt-enhanced/Qtopia |
| application running on my handheld, cell phone, or PC using the Linux |
| console framebuffer (i.e. not X11)? |
| |
| Yes, the basic method for this is the -rawfb scheme where the Linux |
| console framebuffer (usually /dev/fb0) is polled and the uinput driver |
| is used to inject keystrokes and mouse input. Often you will just have |
| to type: |
| x11vnc -rawfb console |
| |
| (you may need to enable the uinput driver on the system via "modprobe |
| uinput; mknod /dev/input/uinput c 10 223") If this does not find the |
| correct frame buffer properties figure them out or guess them and use |
| something like: |
| x11vnc -rawfb /dev/fb0@640x480x16 |
| |
| Also, to force usage of the uinput injection method use "-pipeinput |
| UINPUT". See the -pipeinput description for tunable parameters, etc. |
| |
| One problem with the x11vnc uinput scheme is that it cannot guess the |
| mouse motion "acceleration" used by the windowing application (e.g. |
| QWS or X11.) For X11 and Qt-embedded the acceleration is usually 2 |
| (i.e. a dx of 1 from the mouse yields a 2 pixel displacement of the |
| mouse cursor.) The default x11vnc uses is 2, since that is often used. |
| However for one Qt-embedded system we needed to do: |
| x11vnc -rawfb console -pipeinput UINPUT:accel=4.0 |
| |
| to get reasonable positioning of the mouse. |
| |
| Even with the correct acceleration setting there is still some drift |
| (probably because of the mouse threshold where the acceleration kicks |
| in) and so x11vnc needs to reposition the cursor from 0,0 about 5 |
| times a second. See the -pipeinput UINPUT option for tuning parameters |
| that can be set (there are some experimental thresh=N tuning |
| parameters as well) |
| |
| Currently, one can expect mouse input to be a little flakey. All in |
| all, the Linux framebuffer input mechanism for Qt-embedded framebuffer |
| apps is not perfect, but it is usable. |
| |
| If you need to create a smaller x11vnc binary for a handheld |
| environment be sure to run strip(1) on it and also consider |
| configuring with, e.g. "env CPPFLAGS='-DSMALL_FOOTPRINT=1' ./configure |
| ..." to remove rarely used features and large texts (use 2 or 3 |
| instead of 1 to remove more.) Currently (Jul/2006) this can lower the |
| size of the x11vnc from 1.1MB to 0.6-0.7MB. |
| |
| The x11vnc uinput method applies to nearly anything on the Linux |
| framebuffer console, not just Qt-embedded/Qtopia. DirectFB, SDL using |
| fbcon driver, SVGAlib applications can also be viewed and interacted |
| with. Even a Linux X session can be viewed and interacted with without |
| using X11 (and x11vnc does not have to terminate when the X server |
| restarts!) The Linux Text consoles (F1-F6) also work. |
| |
| Note that Qt-embedded supplies its own VNC graphics driver, but it |
| cannot do both the Linux console framebuffer and VNC at the same time, |
| which is often what is desired from VNC. |
| |
| Update: We are finding some setups like Qtopia on the IPAQ do not |
| allow mouse input via uinput. Please help us debug this problem by |
| trying x11vnc on your device and letting us know what does and does |
| not work. See the next FAQ for a possible workaround for touchscreens. |
| |
| |
| Q-116: How do I inject touch screen input into an |
| Qt-embedded/Qt-enhanced/Qtopia cell phone such as openmoko/qtmoko Neo |
| Freerunner? |
| |
| The qtmoko project does not use X11 for the graphical display. |
| Unfortunately the Linux uinput method described in the previous FAQ |
| does not work because Qt is using TSLIB (touch screen library) to |
| process the input and it only reads from one device (often |
| /dev/input/event1) and not from the new UINPUT device that x11vnc |
| creates (under -pipeinput UINPUT) |
| |
| So something else needs to be done. It was discovered that by simply |
| writing the touchscreen events directly to /dev/input/event1 then |
| input can be injected into the system. There is no x11vnc builtin mode |
| for this yet (until we understand it better), but there is a working |
| script provided in x11vnc/misc/qt_tslib_inject.pl. So one could use it |
| this way for example: |
| x11vnc ... -rawfb console -pipeinput path/to/qt_tslib_inject.pl -env INJECT_O |
| PTIONS=clickonly,cal=/etc/pointercal |
| |
| Read the script for how to enable other options and what the above |
| options mean (e.g. /etc/pointercal contains TSLIB's calibration |
| parameters and are necessary to achieve accurate pointing.) |
| |
| The x11vnc/misc/qt_tslib_inject.pl script can potentially be modified |
| to handle other devices where the uinput method fails. It could also |
| be modified to create 'hot keys', etc. |
| |
| Please let us know how things go if you try this out; there is much to |
| learn about synthetic input injection in handhelds and cell phones. As |
| we learn more we can develop a builtin x11vnc mode for this sort of |
| injection. |
| |
| Update Dec/2010: There is experimental built-in UINPUT support in the |
| x11vnc development tarball for qtmoko with touchpad managed by tslib. |
| See -pipeinput UINPUT for more info. Here is an example: |
| x11vnc -rawfb console -pipeinput UINPUT:touch,tslib_cal=/etc/pointercal,dire |
| ct_abs=/dev/input/event1,nouinput,dragskip=3 |
| |
| |
| Q-117: Now that non-X11 devices can be exported via VNC using x11vnc, |
| can I build it with no dependencies on X11 header files and libraries? |
| |
| Yes, as of Jul/2006 x11vnc enables building for -rawfb only support. |
| Just do something like when building: |
| ./configure --without-x (plus any other flags) |
| make |
| |
| You can then test via "ldd x11vnc" that the binary does not depend on |
| libX11.so, etc. See the previous FAQ's for non-X11 framebuffer usage. |
| If you use this for an interesting non-X11 application please let us |
| know what you did. |
| |
| |
| Q-118: How do I cross compile x11vnc for a different architecture than |
| my Linux i386 or amd64 PC? |
| |
| You will need a cross-compiling toolchain. Perhaps your distro |
| provides these or you can find a HOWTO for your distro. We found a |
| nice one at qtmoko.org for building armel binaries on Debian Linux |
| i386 machines. It includes most of the libraries that x11vnc needs. We |
| use that example here. |
| |
| We ran this script to set PATH, configure, and build: |
| #!/bin/sh |
| |
| # toolchain from: qtmoko-debian-toolchain-armv4t-eabi.tar.gz |
| |
| export PATH=/opt/toolchains/arm920t-eabi/bin:$PATH |
| |
| env CC=arm-linux-gcc ./configure --host=arm-linux --without-avahi |
| |
| make |
| |
| arm-linux-strip ./x11vnc/x11vnc |
| ls -l ./x11vnc/x11vnc |
| |
| Note we had to include --without-avahi due to lack of |
| libavahi-client.so.3 supplied by the toolchain we used. One would need |
| to add it if it was desired on the target machine. We also stripped |
| the binary to make it smaller. |
| |
| For an embedded system one may also want to add --without-x if the |
| embedded system does not use X11 and the -rawfb mechanism must be |
| used. |
| |
| |
| Q-119: Does x11vnc support Mac OS X Aqua/Quartz displays natively |
| (i.e. no X11 involved)? |
| |
| Yes, since Nov/2006 in the development tree (x11vnc-0.8.4 tarball) |
| there is support for native Mac OS X Aqua/Quartz displays using the |
| -rawfb mechanism described above. The mouse and keyboard input is |
| achieved via Mac OS X API's. |
| |
| So you can use x11vnc as an alternative to OSXvnc (aka Vine Server), |
| or Apple Remote Desktop (ARD). Perhaps there is some x11vnc feature |
| you'd like to use on Mac OS X, etc. For a number of activities (e.g. |
| window drags) it seems to be faster than OSXvnc. |
| |
| Notes: |
| |
| X11: x11vnc will also work (as it has for years) with a X11 server |
| (XDarwin) running on Mac OS X (people often install this software to |
| display remote X11 apps on their Mac OS X system, or use some old |
| favorites locally such as xterm.) However in this case x11vnc will |
| only work reasonably in single window -id windowid mode (and the |
| window may need to have mouse focus.) |
| |
| If you do not have the DISPLAY env. variable set, x11vnc will assume |
| native Aqua/Quartz on Mac OS X, however if DISPLAY is set it will |
| assume an X11 connection. Use "-rawfb console" to force the native |
| display (or unset DISPLAY.) |
| |
| Update: Leopard sets DISPLAY by default in all sessions. Since it |
| starts with the string "/tmp/" x11vnc will use that to know if it |
| should ignore it. Use "-display :0.0" to force it. |
| |
| Building: If you don't have the X11 build and runtime packages |
| installed you will need to build it like this: |
| (cd to the e.g. x11vnc-0.9, source directory) |
| ./configure --without-x |
| make |
| |
| Win2VNC/x2vnc: One handy use is to use the -nofb mode to redirect |
| mouse and keyboard input to a nearby Mac (i.e. one to the side of your |
| desk) via x2vnc or Win2VNC. See this FAQ for more info. |
| |
| Options: Here are the Mac OS X specific x11vnc options: |
| -macnodim For the native Mac OS X server, disable dimming. |
| -macnosleep For the native Mac OS X server, disable display sleep |
| . |
| -macnosaver For the native Mac OS X server, disable screensaver. |
| -macnowait For the native Mac OS X server, do not wait for the |
| user to switch back to his display. |
| -macwheel n For the native Mac OS X server, set the mouse wheel |
| speed to n (default 5.) |
| -macnoswap For the native Mac OS X server, do not swap mouse |
| buttons 2 and 3. |
| -macnoresize For the native Mac OS X server, do not resize or rese |
| t |
| the framebuffer even if it is detected that the scree |
| n |
| resolution or depth has changed. |
| -maciconanim n For the native Mac OS X server, set n to the number |
| of milliseconds that the window iconify/deiconify |
| animation takes. In -ncache mode this value will be |
| used to skip the animation if possible. (default 400) |
| -macmenu For the native Mac OS X server, in -ncache client-sid |
| e |
| caching mode, try to cache pull down menus (not perfe |
| ct |
| because they have animated fades, etc.) |
| |
| PasteBoard/Clipboard: There is a bug that the Clipboard (called |
| PasteBoard on Mac it appears) exchange will not take place unless |
| x11vnc was started from inside the Aqua display (e.g. started inside a |
| Terminal app window.) Otherwise it cannot connect to the PasteBoard |
| server. So Clipboard exchange won't work for our standard "ssh in" |
| startup scheme. |
| |
| Hopefully this deficiency can be removed, but until then for Clipboard |
| exchange to work you will need to start x11vnc inside the desktop |
| session (i.e. either start it running before you leave, or start up a |
| 2nd x11vnc inside from a 1st one started outside, or use the apple |
| script below) |
| |
| Here also is a osascript trick that seems to work (it opens the |
| Terminal app and instructs it to start x11vnc): |
| |
| #!/bin/sh |
| # |
| # start_x11vnc: start x11vnc in a Terminal window |
| # (this will allow Clipboard/Pasteboard exchange to work) |
| |
| tmp=/tmp/start_x11vnc.$$ |
| |
| cat > $tmp <<END |
| |
| tell application "Terminal" |
| activate |
| do script with command "$HOME/x11vnc -rfbauth .vnc/passwd -ssl SAVE" |
| end tell |
| |
| END |
| |
| osascript $tmp |
| rm -f $tmp |
| |
| where you should customize the x11vnc command line to your needs and |
| the full path to the binary. Save it in a file e.g. "start_x11vnc" and |
| then after you SSH in just type "./start_x11vnc" (or have ssh run the |
| command for you.) Then once you are connected via VNC, iconify the |
| Terminal windows (you can't delete them since that will kill x11vnc.) |
| |
| Update Aug/2010: A user reports the following useful information: |
| This is not a problem on Mac OS X 10.6.x (Snow Leopard) when connecting |
| via ssh to start x11vnc. And, on Mac OS X 10.5.x (Leopard), the problem |
| can be permanently eliminated by doing this: |
| |
| |
| sudo /usr/libexec/PlistBuddy -c 'delete :LimitLoadToSessionType' \ |
| -c 'add :LimitLoadToSessionType string Background' \ |
| /System/Library/LaunchAgents/com.apple.pboard.plist |
| # ignore any 'Delete: Entry, ":LimitLoadToSessionType", Does Not Exist' message |
| |
| and then restarting (yes, you must restart not just log off). But |
| ONLY do that for Mac OS X 10.5.x and NOT for 10.6.x (which doesn't |
| need it anyway). |
| |
| We recently got access to a MacOSX 10.6.4 (Snow Leopard) macbook and |
| have confirmed that the above is correct. |
| |
| |
| Q-120: Can x11vnc be used as a VNC reflector/repeater to improve |
| performance for the case of a large number of simultaneous VNC viewers |
| (e.g. classroom broadcasting or a large demo)? |
| |
| Yes, as of Feb/2007 there is the "-reflect host:N" option to connect |
| to the VNC server "host:N" (either another x11vnc or any other VNC |
| server) and re-export it. VNC viewers then connect to the x11vnc(s) |
| running -reflect. |
| |
| The -reflect option is the same as: "-rawfb vnc:host:N". See the |
| -rawfb description under "VNC HOST" for more details. |
| |
| You can replace "host:N" with "listen" or "listen:port" for reverse |
| connections. |
| |
| One can set up a number of such reflectors/repeaters to spread the |
| resource usage around, e.g.: |
| C -------<-------| |
| C -------<-------| |
| C -------<-------|---- R -----| |
| C -------<-------| | |
| C -------<-------| | |
| | |
| C -------<-------| | |
| C -------<-------| | |
| C -------<-------|---- R -----| |
| C -------<-------| | |
| C -------<-------| | |
| |====== S |
| C -------<-------| | |
| C -------<-------| | |
| C -------<-------|---- R -----| |
| C -------<-------| | |
| C -------<-------| | |
| | |
| C -------<-------| | |
| C -------<-------| | |
| C -------<-------|---- R -----| |
| C -------<-------| |
| C -------<-------| |
| |
| Where "S" is the original VNC Server, "C" denote VNC viewer clients, |
| and "R" denotes an x11vnc running -reflect to "S". |
| |
| Ideally, a client "C" will be fairly close network-wise to its "R". It |
| is fine to run the "R" on the same machine as one of its "C's". A nice |
| setup for a large, (e.g. 64-128) viewer classroom broadcast case would |
| be to run R's on areas isolated by network switches, e.g. one R per |
| switch. |
| |
| In an extreme case (e.g. 1000 viewers) one might actually need a 2nd |
| layer of R's in the tree. If you try something like that let us know! |
| |
| There are many resource savings in doing something like the above. The |
| first obvious one is network bandwidth savings. Another is less CPU |
| load on "S" since it handles many fewer simultaneous connections. |
| Also, if there are a few clients C on very slow links, their presence |
| does not slow down every other client, just the clients on their "R". |
| One way a slow client affects things is if there are some large |
| framebuffer writes (e.g. jpeg image region) then the repeater may |
| block waiting for that large write to finish before going onto the |
| next client (however, if the write is small enough, the kernel will |
| buffer it and the server can go on to service the next client.) |
| |
| The x11vnc -reflect implementation uses the libvncclient library in |
| the LibVNCServer project to handle the connection to "S". It is not |
| currently very efficient since it simply does its normal framebuffer |
| polling scheme on the libvncclient framebuffer (which it then |
| re-exports via VNC to its clients C.) However, CopyRect and |
| CursorShape encodings are preserved in the reflection and that helps. |
| Dragging windows with the mouse can be a problem (especially if S is |
| not doing wireframing somehow, consider -nodragging if the problem is |
| severe) For a really fast reflector/repeater it would have to be |
| implemented from scratch with performance in mind. See these other |
| projects: |
| http://sourceforge.net/projects/vnc-reflector/, |
| http://www.tightvnc.com/projector/ (closed source?), |
| |
| |
| Automation via Reverse Connections: Instead of having the R's |
| connect directly to S and then the C's connect directly to the R they |
| should use, some convenience can be achieved by using reverse |
| connections (the x11vnc ""-connect host1,host2,..." option.) Suppose |
| all the clients "C" are started up in Listen mode: |
| client1> vncviewer -listen |
| client2> vncviewer -listen |
| client3> vncviewer -listen |
| ... |
| client64> vncviewer -listen |
| |
| (e.g. client1> is the cmdline prompt on machine client1 ... etc) and |
| all the repeaters R are started like this: |
| repeater1> x11vnc -reflect listen -connect client1,client2,...client8 |
| repeater2> x11vnc -reflect listen -connect client9,client10,...client16 |
| ... |
| repeater8> x11vnc -reflect listen -connect client57,client58,...client64 |
| |
| and finally the main server is started to kick the whole thing into |
| motion: |
| vncserver> x11vnc -display :0 -connect repeater1,repeater2,...repeater8 |
| |
| (or instruct a non-x11vnc VNC server to reverse connect to the |
| repeaters.) For a classroom broadcasting setup one might have the |
| first two sets of commands start automatically at bootup or when |
| someone logs in, and then start everything up with the S server. One |
| may even be able to script the forward connection bootstrap case, let |
| us know what you did. A really nice thing would be some sort of |
| auto-discovery of your repeater, etc... |
| |
| Q-121: Can x11vnc be used during a Linux, Solaris, etc. system |
| Installation so the Installation can be done remotely? |
| |
| This can be done, but it doesn't always work because it depends on how |
| the OS does its install. We have to "sneak in" somehow. Note that some |
| OS's have a remote install (ssh etc.) built in and so you might want |
| to use that instead. |
| |
| Usually the OS install will have to be a network-install in order to |
| have networking up during the install. Otherwise, you may have a |
| (slim) chance to configure the networking manually (ifconfig(8) and |
| route(8).) |
| |
| To avoid library dependencies problems in the typical minimal (e.g. |
| busybox) installation OS it is a good idea to build a statically |
| linked x11vnc binary. A way that often works is to do a normal build |
| and then paste the final x11vnc link line into a shell script. Then |
| change the "gcc" to "gcc -static" and run the shell script. You may |
| need to disable features (e.g. "--without-xfixes") if there is not a |
| static library for the feature available. You may also need to add |
| extra link options (e.g. "-lXrender") to complete library dependencies |
| manually. |
| |
| Let's call the binary x11vnc.static. Place it on a webserver |
| somewhere. It may be possible to retrieve it via scp(1) too. |
| |
| During the install you need to get a shell to retreive x11vnc.static |
| and run it. |
| |
| If the Solaris install is an older X-based one, there will be a menu |
| for you to get a terminal window. From that window you might be able |
| to retrieve x11vnc.static via wget, scp, or ftp. Remember to do "chmod |
| 755 ./x11vnc.static" and then find the -auth file as in this FAQ. |
| |
| If it is a Linux install that uses an X server (e.g. SuSE and probably |
| Fedora), then you can often get a shell by pressing Ctrl-Alt-F2 or |
| similar. Then get the x11vnc binary via something like this: |
| cd /tmp |
| wget http://192.168.0.22/x11vnc.static |
| chmod 755 ./x11vnc.static |
| |
| Find the name of the auth file as in this FAQ. (maybe run "ps wwaux | |
| grep auth".) Then run it like this: |
| ./x11vnc.static -forever -nopw -display :0 -auth /tmp/wherever/the/authfile |
| |
| then press Alt-F7 to go back to the X install. You should now be able |
| to connect via a vnc viewer and continue the install. Watch out for |
| the display being :1, etc. |
| |
| If there is a firewall blocking incoming connections during the |
| install, use the "-connect hostname" option option for a reverse |
| connection to the hostname running the VNC viewer in listen mode. |
| |
| Debian based installs are either console-text or console-framebuffer |
| based. These are install (or expert) and installgui (or expertgui) |
| boot lines, respectively. For the console-text based installs you |
| probably need to add a boot cmd line option like vga=0x314 (which is |
| 800x600x16) to get the console-text to use the linux framebuffer |
| device properly. |
| |
| For a Debian console-text based install after the network is |
| configured press Ctrl-Alt-F2 to get a shell. Retrieve the binary via |
| wget as above and chmod 755 it. Then run it something like this: |
| sleep 10; ./x11vnc.static -forever -nopw -rawfb console |
| |
| then before the sleep is over press Alt-F1 to get back to the install |
| virtual console. You should be able to connect via a VNC viewer and |
| continue with the install. |
| |
| For a recent (2009) Debian install we booted with "expert vga=0x301" |
| and "expert vga=0x311" to get console text based installs at 640x480x8 |
| and 640x480x16, respectively (replace "expert" with "install" if you |
| like.) Otherwise it was giving a 16 color 640x480x4 (4 bit per pixel) |
| display which x11vnc could not handle. |
| |
| For Debian console-framebuffer GUI based installs (installgui or |
| expertgui) we have not be able to enter keystrokes or mouse motions. |
| This may be resolved if the install had the Linux kernel module |
| uinput, but it doesn't; one can wget uinput.ko and then run insmod on |
| it, but the module must match the installation kernel. So, failing |
| that, you can only do the GUI view-only, which can be handy to watch a |
| long network install from your desk instead of in front of the machine |
| being installed. For these, after the network is configured press |
| Ctrl-Alt-F2 to get a shell. Retrieve the binary via wget as above and |
| chmod 755 it. Then run it something like this: |
| sleep 10; ./x11vnc.static -forever -nopw -rawfb console |
| |
| then before the sleep is over press Alt-F5 to get back to the GUI |
| install console. You should be able to connect via a VNC viewer and |
| watch the install. |
| [Misc: Clipboard, File Transfer/Sharing, Printing, Sound, Beeps, |
| Thanks, etc.] |
| |
| Q-122: Does the Clipboard/Selection get transferred between the |
| vncviewer and the X display? |
| |
| As of Jan/2004 x11vnc supports the "CutText" part of the RFB (aka VNC) |
| protocol. When text is selected/copied in the X session that x11vnc is |
| polling it will be sent to connected VNC viewers. And when CutText is |
| received from a VNC viewer then x11vnc will set the X11 selections |
| PRIMARY, CLIPBOARD, and CUTBUFFER0 to it. x11vnc is able to hold the |
| PRIMARY and CLIPBOARD selections (Xvnc does not seem to do this.) |
| |
| The X11 selections can be confusing, especially to those coming from |
| Windows or MacOSX where there is just a single 'Clipboard'. The X11 |
| CLIPBOARD selection is a lot like that of Windows and MacOSX, e.g. |
| highlighted text is sent to the clipboard when the user activates |
| "Edit -> Copy" or presses "Control+C" (and pasting it via "Edit -> |
| Paste" or "Control+V".) The X11 PRIMARY selection has been described |
| as 'for power users' or 'an Easter Egg'. As soon as text is |
| highlighted it is set to the PRIMARY selection and so it is |
| immediately ready for pasting, usually via the Middle Mouse Button or |
| "Shift+Insert". See this jwz link for more information. |
| |
| x11vnc's default behavior is to watch both CLIPBOARD and PRIMARY and |
| whenever one of them changes, it sends the new text to connected |
| viewers. Note that since the RFB protocol only has a single "CutText" |
| then both selections are "merged" to some degree (and this can lead to |
| confusing results.) One user was confused why x11vnc was "forgetting" |
| his CLIPBOARD selection and the reason was he also changed PRIMARY |
| some time after he copied text to the clipboard. Usually an app will |
| set PRIMARY as soon as any text is highlighted so it easy to see how |
| CLIPBOARD was forgotten. Use the -noprimary described below as a |
| workaround. Similarly, by default when x11vnc receives CutText it sets |
| both CLIPBOARD and PRIMARY to it (this is probably less confusing, but |
| could possibly lead to some failure modes as well.) |
| |
| You may not like these defaults. Here are ways to change the behavior: |
| * If you don't want the Clipboard/Selection exchanged at all use the |
| -nosel option. |
| * If you want changes in PRIMARY to be ignored use the -noprimary |
| option. |
| * If you want changes in CLIPBOARD to be ignored use the |
| -noclipboard option. |
| * If you don't want x11vnc to set PRIMARY to the "CutText" received |
| from viewers use the -nosetprimary option. |
| * If you don't want x11vnc to set CLIPBOARD to the "CutText" |
| received from viewers use the -nosetclipboard option. |
| |
| You can also fine-tune it a bit with the -seldir dir option and also |
| -input. |
| |
| You may need to watch out for desktop utilities such as KDE's |
| "Klipper" that do odd things with the selection, clipboard, and |
| cutbuffers. |
| |
| |
| Q-123: Can I use x11vnc to record a Shock Wave Flash (or other format) |
| video of my desktop, e.g. to record a tutorial or demo? |
| |
| Yes, it is possible with a number of tools that record VNC and |
| transform it to swf format or others. One such popular tool is |
| pyvnc2swf. There are a number of tutorials (broken link?) on how to do |
| this. Another option is to use the vnc2mpg that comes in the |
| LibVNCServer package. |
| An important thing to remember when doing this is that tuning |
| parameters should be applied to x11vnc to speed up its polling for |
| this sort of application, e.g. "-wait 10 -defer 10". |
| |
| Q-124: Can I transfer files back and forth with x11vnc? |
| |
| As of Oct/2005 and May/2006 x11vnc enables, respectively, the TightVNC |
| and UltraVNC file transfer implementations that were added to |
| libvncserver. This currently works with TightVNC and UltraVNC viewers |
| (and Windows viewers only support filetransfer it appears... but they |
| do work to some degree under Wine on Linux.) |
| |
| The SSVNC Unix VNC viewer supports UltraVNC file transfer by use of a |
| Java helper program. |
| |
| TightVNC file transfer is off by default, if you want to enable it use |
| the -tightfilexfer option. |
| |
| UltraVNC file transfer is off by default, to enable it use something |
| like "-rfbversion 3.6 -permitfiletransfer" |
| options (UltraVNC incorrectly uses the RFB protocol version to |
| determine if its features are available, so x11vnc has to pretend to |
| be version 3.6.) As of Sep/2006 "-ultrafilexfer" is an alias for these |
| two options. Note that running as RFB version 3.6 may confuse other |
| VNC Viewers. |
| |
| Sadly you cannot do both -tightfilexfer and -ultrafilexfer at the same |
| time because the latter requires setting the version to 3.6 and |
| tightvnc will not do filetransfer when it sees that version number. |
| |
| Also, because of the way the LibVNCServer TightVNC file transfer is |
| implemented, you cannot do Tightvnc file transfer in -unixpw mode. |
| However, UltraVNC file transfer does work in -unixpw (but if a client |
| tries it do a filetransfer during the login process it will be |
| disconnected.) |
| |
| IMPORTANT: please understand if -ultrafilexfer or -tightfilexfer is |
| specified and you run x11vnc as root for, say, inetd or display |
| manager (gdm, kdm, ...) access and you do not have it switch users via |
| the -users option, then VNC Viewers that connect are able to do |
| filetransfer reads and writes as *root*. |
| |
| The UltraVNC and TightVNC settings can be toggled on and off inside |
| the gui or by -R remote control. However for TightVNC the changed |
| setting only applies for NEW clients, current clients retain their |
| TightVNC file transfer ability. For UltraVNC it works better, however |
| if an UltraVNC client has initiated a file transfer dialog it will |
| remain in effect until the dialog is closed. If you want to switch |
| between UltraVNC and TightVNC file transfer in the gui or by remote |
| control you will probably be foiled by the "-rfbversion 3.6" issue. |
| |
| |
| Q-125: Which UltraVNC extensions are supported? |
| |
| Some of them are supported. To get UltraVNC Viewers to attempt to use |
| these extensions you will need to supply this option to x11vnc: |
| -rfbversion 3.6 |
| |
| Or use -ultrafilexfer which is an alias for the above option and |
| "-permitfiletransfer". UltraVNC evidently treats any other RFB version |
| number as non-UltraVNC. |
| |
| Here are a list of the UltraVNC extensions supported by x11vnc: |
| * ServerInput: "Toggle Remote Input and Remote Blank Monitor" |
| * FileTransfer: "Open File Transfer..." |
| * SingleWindow: "Select Single Window..." |
| * TextChat: "Open Chat..." |
| * 1/n Server Scaling |
| |
| The SSVNC Unix VNC viewer supports these UltraVNC extensions. |
| |
| To disable SingleWindow and ServerInput use -noultraext (the others |
| are managed by LibVNCServer.) See this option too: -noserverdpms. |
| |
| Also, the UltraVNC repeater proxy is supported for use with reverse |
| connections: "-connect repeater://host:port+ID:NNNN". Use it for both |
| plaintext and SSL connections. This mode can send any string before |
| switching to the VNC protocol, and so could be used with other |
| proxy/gateway tools. Also, a perl repeater implemention is here: |
| ultravnc_repeater.pl |
| |
| |
| Q-126: Can x11vnc emulate UltraVNC's Single Click helpdesk mode for |
| Unix? I.e. something very simple for a naive user to initiate a |
| reverse vnc connection from their Unix desktop to a helpdesk |
| operator's VNC Viewer. |
| |
| Yes, UltraVNC's Single Click (SC) mode can be emulated fairly well on |
| Unix. |
| |
| We use the term "helpdesk" below, but it could be any sort of remote |
| assistance you want to set up, e.g. something for Unix-using friends |
| or family to use. This includes Mac OS X. |
| |
| Assume you create a helpdesk directory "hd" on your website: |
| http://www.mysite.com/hd (any website that you can upload files to |
| should work, although remember the user will be running the programs |
| you place there.) |
| |
| In that "hd" subdirectory copy an x11vnc binary to be run on the Unix |
| user's machine (e.g. Linux, etc) and also create a file named "vnc" |
| containing the following: |
| #!/bin/sh |
| |
| webhost="http://www.mysite.com/hd" # Your helpdesk dir URL. |
| |
| vnchost="ip.someplace.net" # Your host running 'vncviewer -listen' |
| # It could also be your IP number. If it is |
| # a router/firewall, you will need to |
| # configure it to redirect port 5500 to you |
| r |
| # workstation running 'vncviewer -listen' |
| |
| dir=/tmp/vnc_helpdesk.$$ # Make a temporary working dir. |
| mkdir $dir || exit 1 |
| cd $dir || exit 1 |
| |
| trap "cd /tmp; rm -rf $dir" 0 2 15 # Cleans up on exit. |
| |
| wget $webhost/x11vnc # Fetch x11vnc binary. If multi- |
| chmod 755 ./x11vnc # platform, use $webhost/`uname`/x11vnc |
| # or similar. |
| |
| ./x11vnc -connect_or_exit $vnchost -rfbport 0 -nopw |
| |
| with the hostnames / IP addresses customized to your case. |
| |
| On the helpdesk VNC viewer machine (ip.someplace.net in this example) |
| you have the helpdesk operator running VNC viewer in listen mode: |
| vncviewer -listen |
| |
| or if on Windows, etc. somehow have the VNC viewer be in "listen" |
| mode. |
| |
| Then, when the naive user needs assistance you instruct him to open up |
| a terminal window on his Unix desktop and paste the following into the |
| shell: |
| wget -qO - http://www.mysite.com/hd/vnc | sh - |
| |
| and then press Enter. You could have this instruction on a web page or |
| in an email you send him, etc. This requires that the wget is |
| installed on the user's Unix machine (he might only have curl or lynx, |
| see below for more info.) |
| |
| |
| So I guess this is about 3-4 clicks (start a terminal and paste) and |
| pressing "Enter" instead of "single click"... |
| |
| See this page for some variations on this method, e.g. how to add a |
| password, SSL Certificates, etc. |
| |
| |
| If you don't have a website (there are many free ones) or don't want |
| to use one you will have to email him all of the ingredients (x11vnc |
| binary and a launcher script) and tell him how to run it. This could |
| be easy or challenging depending on the skill of the naive unix |
| user... |
| |
| A bit of obscurity security could be put in with a -passwd, -rfbauth |
| options, etc. (note that x11vnc will require a password even for |
| reverse connections.) More info here. |
| |
| |
| Firewalls: If the helpdesk (you) with the vncviewer is behind a |
| NAT/Firewall/Router the router will have to be configured to redirect |
| a port (i.e. 5500 or maybe different one if you like) to the vncviewer |
| machine. If the vncviewer machine also has its own host-level |
| firewall, you will have to open up the port there as well. |
| |
| NAT-2-NAT: There is currently no way to go "NAT-2-NAT", i.e. both User |
| and Helpdesk workstations behind NAT'ing Firewall/Routers without |
| configuring a router to do a port redirection (i.e. on your side, the |
| HelpDesk.) To avoid modifying either firewall/router, one would need |
| some public (IP address reachable on the internet) redirection/proxy |
| service. Perhaps such a thing exists. http://sc.uvnc.com provides this |
| service for their UltraVNC Single Click users. |
| |
| Update: It may be possible to do "NAT-2-NAT" with a UDP tunnel such as |
| http://samy.pl/pwnat/. All that is required is that both NAT firewalls |
| allow in UDP packets from an IP address to which a UDP packet has |
| recently been sent to. If you try it out let us know how it went. |
| |
| |
| Very Naive Users: |
| |
| If it is beyond the user how to open a terminal window and paste in a |
| command (you have my condolences...) you would have to somehow setup |
| his Web browser to download the "vnc" file (or a script containing the |
| above wget line) and prompt the user if he wants to run it. This may |
| be tricky to set up (which is probably a good thing to not have the |
| web browser readily run arbitrary programs downloaded from the |
| internet...) |
| |
| One command-line free way, tested with KDE, is to name the file vnc.sh |
| and then instruct the user to right-click on the link and do "Save |
| Link As" to his Desktop. It will appear as an icon, probably one that |
| looks like a terminal or a command line prompt. He next should |
| right-click on the icon and select "Properties" and go to the |
| "Permissions" tab. Then in that dialog select the checkbox "Is |
| executable". He should then be able to click on the icon to launch it. |
| Another option is to right-click on the icon and select "Open With -> |
| Other ..." and for the name of the application type in "/bin/sh". |
| Unfortunately in both cases the command output is lost and so errors |
| cannot be debugged as easily. A similar thing appears to work in GNOME |
| if under "Properties -> Permissions" they click on "Execute" checkbox |
| for "Owner". Then when they click on the icon, they will get a dialog |
| where they can select "Run in Terminal". In general for such cases, if |
| it is feasible, it might be easier to ssh to his machine and set |
| things up yourself... |
| |
| |
| SSL Encrypted Helpdesk Connections: |
| |
| As of Apr/2007 x11vnc supports reverse connections in SSL and so we |
| can do this. On the Helpdesk side (Viewer) you will need STUNNEL or |
| better use the Enhanced TightVNC Viewer (SSVNC) package we provide |
| that automates all of the SSL for you. |
| |
| To do this create a file named "vncs" in the website "hd" directory |
| containing the following: |
| #!/bin/sh |
| |
| webhost="http://www.mysite.com/hd" # Your helpdesk dir URL. |
| |
| vnchost="ip.someplace.net" # Your host running 'vncviewer -listen' |
| # It could also be your IP number. If it is |
| # a router/firewall, you will need to |
| # configure it to redirect port 5500 to you |
| r |
| # workstation running 'vncviewer -listen' |
| |
| dir=/tmp/vnc_helpdesk.$$ # Make a temporary working dir. |
| mkdir $dir || exit 1 |
| cd $dir || exit 1 |
| |
| trap "cd /tmp; rm -rf $dir" 0 2 15 # Cleans up on exit. |
| |
| wget $webhost/x11vnc # Fetch x11vnc binary. If multi- |
| chmod 755 ./x11vnc # platform, use $webhost/`uname`/x11vnc |
| # or similar. |
| |
| ./x11vnc -connect_or_exit $vnchost -rfbport 0 -nopw -ssl # Note -ssl option. |
| |
| with the hostnames or IP addresses customized to your case. |
| |
| The only change from the "vnc" above is the addition of the -ssl |
| option to x11vnc. This will create a temporary SSL cert: openssl(1) |
| will need to be installed on the user's end. A fixed SSL cert file |
| could be used to avoid this (and provide some authentication; more |
| info here.) |
| |
| The naive user will be doing this: |
| wget -qO - http://www.mysite.com/hd/vncs | sh - |
| |
| (or perhaps even use https:// if available.) |
| |
| But before that, the helpdesk operator needs to have "vncviewer |
| -listen" running as before, however he needs an SSL tunnel at his end. |
| The easiest way to do this is use Enhanced TightVNC Viewer (SSVNC). |
| Start it, and select Options -> 'Reverse VNC Connection (-listen)'. |
| Then UN-select 'Verify All Certs' (this can be enabled later if you |
| want; you'll need the x11vnc SSL certificate), and click 'Listen'. |
| |
| If you don't want to use SSVNC for the viewer, but rather set up |
| STUNNEL manually instead, make a file "stunnel.cfg" containing: |
| foreground = yes |
| pid = |
| |
| [vnc] |
| accept = 5500 |
| connect = localhost:5501 |
| |
| and run: |
| stunnel ./stunnel.cfg |
| |
| and then start the "vncviewer -listen 1" (i.e. 1 to correspond to the |
| 5501 port.) Note that this assumes the stunnel install created a |
| Server SSL cert+key, usually /etc/stunnel/stunnel.pem (not all distros |
| will do this.) Also, that file is by default only readable by root, so |
| stunnel needs to be run as root. If your system does not have a key |
| installed or you do not want to run stunnel as root (or change the |
| permissions on the file), you can use x11vnc to create one for you for |
| example: |
| x11vnc -sslGenCert server self:mystunnel |
| |
| answer the prompts with whatever you want; you can take the default |
| for all of them if you like. The openssl(1) package must be installed. |
| See this link and this one too for more info on SSL certs. This |
| creates $HOME/.vnc/certs/server-self:mystunnel.pem, then you would |
| change the "stunnel.cfg" to look something like: |
| foreground = yes |
| pid = |
| cert = /home/myusername/.vnc/certs/server-self:mystunnel.pem |
| |
| [vnc] |
| accept = 5500 |
| connect = localhost:5501 |
| |
| In any event, with stunnel having been setup, the naive user is |
| instructed to paste in and run: |
| wget -qO - http://www.mysite.com/hd/vncs | sh - |
| |
| to pick up the vncs script this time. |
| |
| Of course if a man-in-the-middle can alter what the user downloads |
| then all bets are off!. |
| |
| More SSL variations and info about certificates can be found here. |
| |
| |
| OpenSSL libssl.so.0.9.7 problems: |
| |
| If you build your own stunnel or x11vnc for deployment, you may want |
| to statically link libssl.a and libcrypto.a into it because Linux |
| distros are currently a bit of a mess regarding which version of |
| libssl is installed. |
| |
| You will find the details here. |
| |
| |
| Q-127: Can I (temporarily) mount my local (viewer-side) Windows/Samba |
| File share on the machine where x11vnc is running? |
| |
| You will have to use an external network redirection for this. |
| Filesystem mounting is not part of the VNC protocol. |
| |
| We show a simple Samba example here. |
| |
| First you will need a tunnel to redirect the SMB requests from the |
| remote machine to the one you sitting at. We use an ssh tunnel: |
| sitting-here> ssh -C -R 1139:localhost:139 far-away.east |
| |
| Or one could combine this with the VNC tunnel at the same time, e.g.: |
| sitting-here> ssh -C -R 1139:localhost:139 -t -L 5900:localhost:5900 far-away |
| .east 'x11vnc -localhost -display :0' |
| |
| Port 139 is the Windows Service port. For Windows systems instead of |
| Samba, you may need to use the actual IP address of the Window machine |
| instead of "localhost" in the -R option (since the Windows service |
| does not listen on localhost by default.) |
| |
| Note that we use 1139 instead of 139 on the remote side because 139 |
| would require root permission to listen on (and you may have a samba |
| server running on it already.) |
| |
| The ssh -C is to enable compression, which might speed up the data |
| transfers. |
| |
| Depending on the remote system side configuration, it may or may not |
| be possible to mount the SMB share as a non-root user. Try it first as |
| a non-root user and if that fails you will have to become root. |
| |
| We will assume the user name is "fred" and we will try to mount the |
| viewer-side Windows SMB share "//haystack/pub" in |
| /home/fred/smb-haystack-pub. |
| far-away> mkdir -p /home/fred/smb-haystack-pub |
| far-away> smbmount //haystack/pub /home/fred/smb-haystack-pub -o username=fre |
| d,ip=127.0.0.1,port=1139 |
| |
| (The 2nd command may need to be run as root.) Then run "df" or "ls -l |
| /home/fred/smb-haystack-pub" to see if it is mounted properly. Consult |
| the smbmount(8) and related documentation (it may require some |
| fiddling to get write permissions correct, etc.) To unmount: |
| far-away> smbumount /home/fred/smb-haystack-pub |
| |
| At some point we hope to fold some automation for SMB ssh redir setup |
| into the Enhanced TightVNC Viewer (SSVNC) package we provide (as of |
| Sep 2006 it is there for testing.) |
| |
| |
| Q-128: Can I redirect CUPS print jobs from the remote desktop where |
| x11vnc is running to a printer on my local (viewer-side) machine? |
| |
| You will have to use an external network redirection for this. |
| Printing is not part of the VNC protocol. |
| |
| We show a simple Unix to Unix CUPS example here. Non-CUPS port |
| redirections (e.g. LPD) should also be possible, but may be a bit more |
| tricky. If you are viewing on Windows SMB and don't have a local cups |
| server it may be trickier still (see below.) |
| |
| First you will need a tunnel to redirect the print requests from the |
| remote machine to the one you sitting at. We use an ssh tunnel: |
| sitting-here> ssh -C -R 6631:localhost:631 far-away.east |
| |
| Or one could combine this with the VNC tunnel at the same time, e.g.: |
| sitting-here> ssh -C -R 6631:localhost:631 -t -L 5900:localhost:5900 far-away |
| .east 'x11vnc -localhost -display :0' |
| |
| Port 631 is the default CUPS port. The above assumes you have a Cups |
| server running on your viewer machine (localhost:631), if not, use |
| something like my-cups-srv:631 (the viewer-side Cups server) in the -R |
| instead. |
| |
| Note that we use 6631 instead of 631 on the remote side because 631 |
| would require root permission to listen on (and you likely have a cups |
| server running on it already.) |
| |
| Now the tricky part: to get applications to notice your cups |
| server/printer on localhost:6631. |
| |
| If you have administrative privilege (i.e. root password) on the |
| x11vnc side where the desktop is running, it should be easy to add the |
| printer through some configuration utility (e.g. in KDE: Utilities -> |
| Printing -> Printing Manager, and then supply admin password, and then |
| Add Printer/Class, and then fill in the inquisitive wizard. Most |
| important is the "Remote IPP server" panel where you put in localhost |
| for Host and 6631 for Port.) The main setting you want to convey is |
| the host is localhost and the port is non-standard (e.g. 6631.) Some |
| configuration utilities will take an Internet Printing Protocol (IPP) |
| URI, e.g. http://localhost:6631/printers/, |
| ipp://localhost:6631/printers/printer-name, |
| ipp://localhost:6631/ipp/printer-name, etc. Check your CUPS |
| documentation and admin interfaces to find what the syntax is and what |
| the "printer name" is. |
| |
| If you do not have root or print admin privileges, but are running a |
| recent (version 1.2 or greater) of the Cups client software, then an |
| easy way to temporarily switch Cups servers is to create the directory |
| and file: $HOME/.cups/client.conf on the remote side with a line like: |
| ServerName localhost:6631 |
| |
| When not using x11vnc for remote access you can comment the above line |
| out with a '#' (or rename the client.conf file), to have normal cups |
| operation. |
| |
| Unfortunately, running applications may need to be restarted to notice |
| the new printers (libcups does not track changes in client.conf.) |
| Depending on circumstances, a running application may actually notice |
| the new printers without restarting (e.g. no print dialog has taken |
| place yet, or there are no CUPS printers configured on the remote |
| side.) |
| |
| Cups client software that is older (1.1) does not support appending |
| the port number, and for newer ones there is a bug preventing it from |
| always working (fixed in 1.2.3.) Kludges like these at the command |
| line will work: |
| far-away> env CUPS_SERVER=localhost IPP_PORT=6631 lpstat -p -d |
| far-away> env CUPS_SERVER=localhost IPP_PORT=6631 lpr -P myprinter file.ps |
| far-away> env CUPS_SERVER=localhost IPP_PORT=6631 firefox |
| |
| but are somewhat awkward since you have to retroactively set the env. |
| var IPP_PORT. Its value cannot be broadcast to already running apps |
| (like the $HOME/.cups/client.conf trick sometimes does.) A common |
| workaround for an already running app is to somehow get it to "Print |
| To File", e.g. file.ps and then use something like the lpr example |
| above. Also, the option "-h host:port" works with CUPS lp(1) and |
| lpr(1). |
| |
| You can also print to Windows shares printers in principle. You may do |
| this with the smbspool(8) command, or configure the remote CUPS via |
| lpadmin(8), etc, to use a printer URI something like |
| smb://machine:port/printer (this may have some name resolution |
| problems WRT localhost.) Also, as with SMB mounting, the port redir |
| (-R) to the Windows machine must use the actual IP address instead of |
| "localhost". |
| |
| At some point we hope to fold some automation for CUPS ssh redir setup |
| into the Enhanced TightVNC Viewer (SSVNC) package we provide (as of |
| Sep 2006 it is there for testing.) |
| |
| |
| Q-129: How can I hear the sound (audio) from the remote applications |
| on the desktop I am viewing via x11vnc? |
| |
| You will have to use an external network audio mechanism for this. |
| Audio is not part of the VNC protocol. |
| |
| We show a simple Unix to Unix esd example here (artsd should be |
| possible too, we have also verified the esd Windows port works for the |
| method described below.) |
| |
| First you will need a tunnel to redirect the audio from the remote |
| machine to the one you sitting at. We use an ssh tunnel: |
| sitting-here> ssh -C -R 16001:localhost:16001 far-away.east |
| |
| Or one could combine this with the VNC tunnel at the same time, e.g.: |
| sitting-here> ssh -C -R 16001:localhost:16001 -t -L 5900:localhost:5900 far-a |
| way.east 'x11vnc -localhost -display :0' |
| |
| Port 16001 is the default ESD uses. So when an application on the |
| remote desktop makes a sound it will connect to this tunnel and be |
| redirected to port 16001 on the local machine (sitting-here in this |
| example.) The -C option is an attempt to compress the audio a little |
| bit. |
| |
| So we next need a local (sitting-here) esd daemon running that will |
| receive those requests and play them on the local sound device: |
| sitting-here> esd -promiscuous -port 16001 -tcp -bind 127.0.0.1 |
| |
| See the esd(1) man page for the meaning of the options (the above are |
| not very secure.) (This method also works with the EsounD windows port |
| esd.exe) |
| |
| To test this sound tunnel, we use the esdplay program to play a simple |
| .wav file: |
| far-away> esdplay -s localhost:16001 im_so_happy.wav |
| |
| If you hear the sound (Captain Kirk in this example), that means you |
| are in great shape. |
| |
| To run individual audio applications you can use the esddsp(1) |
| command: |
| far-away> esddsp -s localhost:16001 xmms |
| |
| Then you could try playing some sounds inside xmms. You could also set |
| the environment variable ESPEAKER=localhost:16001 to not need to |
| supply the -s option all the time. (for reasons not clear, sometimes |
| esddsp can figure it out on its own.) All the script esddsp does is to |
| set ESPEAKER and LD_PRELOAD for you so that when the application opens |
| the sound device (usually /dev/dsp) its interactions with the device |
| will be intercepted and sent to the esd daemon running on sitting-here |
| (that in turn writes them to the real, local /dev/dsp.) |
| |
| Redirecting All sound: |
| |
| It does not seem to be possible to switch all of the sound of the |
| remote machine from its sound device to the above esd+ssh tunnel |
| without some preparation. But it can be done reasonably well if you |
| prepare (i.e. restart) the desktop with this in mind. |
| |
| Here is one way to redirect all sound. The idea is we run the entire |
| desktop with sound directed to localhost:16001. When we are sitting at |
| far-away.east we run "esd -promiscuous -port 16001 -tcp -bind |
| 127.0.0.1" on far-away.east (to be able to hear the sound.) However, |
| when we are sitting at sitting-here.west we kill that esd process and |
| run that same esd command on sitting-here.west and start up the above |
| ssh tunnel. This is a little awkward, but with some scripts one would |
| probably kill and restart the esd processes automatically when x11vnc |
| is used. |
| |
| So next we have to run the whole desktop pointing toward our esd. Here |
| is a simple way to test. Log in to the machine via the "FailSafe" |
| desktop. Then in the lone terminal type something like: |
| esddsp -s localhost:16001 gnome-session |
| or: |
| esddsp -s localhost:16001 startkde |
| |
| where the last part is whatever command starts your desktop (even |
| fvwm2.) This causes the environment variables ESPEAKER and LD_PRELOAD |
| to be set appropriately and every application (processes with the |
| desktop as an ancestor) will use them. If this scheme works well you |
| can make it less klunky by adding the command to your ~/.xsession, |
| etc. file that starts your default desktop. Or you may be able to |
| configure your desktop to use localhost:16001, or whatever is needed, |
| via a gui configuration panel. Some Notes: |
| * Not all audio applications are compatible with the esd and artsd |
| mechanisms, but many are. |
| * The audio is not compressed so you probably need a broadband or |
| faster connection. Listening to music may not be very pleasant... |
| (Although we found streaming music from across the US over cable |
| modem worked OK, but took 200 KB/sec, to use less bandwidth |
| consider something like "ssh far-away.east 'cat favorite.mp3' | |
| mpg123 -b 4000 -") |
| * Linux does not seem to have the concept of LD_PRELOAD_64 so if you |
| run on a mixed 64- and 32-bit ABI system (e.g. AMD x86_64) some of |
| the applications will fail to run because LD_PRELOAD will point to |
| libraries of the wrong wordsize. |
| * At some point we hope to fold some automation for esd or artsd ssh |
| redir setup into the Enhanced TightVNC Viewer (SSVNC) package we |
| provide (as of Sep/2006 it is there for testing.) |
| |
| |
| Q-130: Why don't I hear the "Beeps" in my X session (e.g. when typing |
| tput bel in an xterm)? |
| |
| As of Dec/2003 "Beep" XBell events are tracked by default. The X |
| server must support the XKEYBOARD extension (this is not on by default |
| in Solaris, see Xserver(1) for how to turn it on via +kb), and so you |
| won't hear them if the extension is not present. |
| |
| If you don't want to hear the beeps use the -nobell option. If you |
| want to hear the audio from the remote applications, consider trying a |
| redirector such as esd. |
| |
| |
| Q-131: Does x11vnc work with IPv6? |
| |
| Update: as of Apr/2010 in the 0.9.10 x11vnc development tarball, there |
| is now built-in support for IPv6 (128 bit internet addresses.) See the |
| -6 and -connect options for details. |
| |
| The remainder of this FAQ entry shows how to do with this with pre |
| 0.9.10 x11vnc using IPv6 helper tools. |
| _________________________________________________________________ |
| |
| Using an external IPv6 helper: |
| A way to do this is via a separate helper program such as inetd (or |
| for encrypted connections: ssh or stunnel.) For example, you configure |
| x11vnc to be run from inetd or xinetd and instruct it to listen on an |
| IPv6 address. For xinetd the setting "flags = IPv6" will be needed. |
| For inetd.conf, an example is: |
| 5900 stream tcp6 nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc_wrapper.sh |
| |
| We also provide a transitional tool in "x11vnc/misc/inet6to4" that |
| acts as a relay for any IPv4 application to allow connections over |
| IPv6. For example: |
| inet6to4 5900 localhost:5900 |
| |
| where x11vnc is listening on IPv4 port 5900. |
| |
| Also note that not all VNC Viewers are IPv6 enabled, so a redirector |
| may also be needed for them. The tool "inet6to4 -r ..." can do this as |
| well. SSVNC (see below) supports IPv6 without need for the helper. |
| |
| # ./inet6to4 -help |
| |
| inet6to4: Act as an ipv6-to-ipv4 relay for tcp applications that |
| do not support ipv6. |
| |
| Usage: inet6to4 |
| inet6to4 -r |
| |
| Examples: inet6to4 5900 localhost:5900 |
| inet6to4 8080 web1:80 |
| inet6to4 -r 5900 fe80::217:f2ff:fee6:6f5a%eth0:5900 |
| |
| The -r option reverses the direction of translation (e.g. for ipv4 |
| clients that need to connect to ipv6 servers.) Reversing is the default |
| if this script is named 'inet4to6' (e.g. by a symlink.) |
| |
| Use Ctrl-C to stop this program. |
| |
| You can also set env. vars INET6TO4_LOOP=1 or INET6TO4_LOOP=BG |
| to have an outer loop restarting this program (BG means do that |
| in the background), and INET6TO4_LOGFILE for a log file. |
| Also set INET6TO4_VERBOSE to verbosity level and INET6TO4_WAITTIME |
| and INET6TO4_PIDFILE (see below.) |
| |
| The "INET6TO4_LOOP=BG" and "INET6TO4_LOGFILE=..." env. variables make |
| the tool run reliably as a daemon for very long periods. Read the top |
| part of the script for more information. |
| _________________________________________________________________ |
| |
| Encrypted Tunnels with IPv6 Support: |
| For SSH tunnelled encrypted VNC connections, one can of course use the |
| IPv6 support in ssh(1). |
| |
| For SSL encrypted VNC connections, one possibility is to use the IPv6 |
| support in stunnel(1). This includes the built-in support via the |
| -stunnel option. For example: |
| x11vnc -stunnel SAVE -env STUNNEL_LISTEN=:: -env STUNNEL_DEBUG=1 ... |
| _________________________________________________________________ |
| |
| SSH IPv6 Tricks: |
| It is interesting to note that ssh(1) can do basically the same thing |
| as inet6to4 above by: |
| ssh -g -L 5900:localhost:5901 localhost "printf 'Press Enter to Exit: '; read |
| x" |
| |
| (where we have x11vnc running via "-rfbport 5901" in this case.) |
| |
| Note that one can also make a home-brew SOCKS5 ipv4-to-ipv6 gateway |
| proxy using ssh like this: |
| ssh -D '*:1080' localhost "printf 'Press Enter to Exit: '; read x" |
| |
| then specify a proxy like socks://hostname:1080 where hostname is the |
| machine running the above ssh command (add -v to ssh for connection |
| logging info.) |
| _________________________________________________________________ |
| |
| IPv6 SSVNC Viewer: |
| Our SSVNC VNC Viewer is basically a wrapper for ssh(1) and stunnel(1), |
| and so it already has good IPv6 support because these two commands do. |
| On Unix, MacOSX, and Windows nearly all of the the remaining parts of |
| SSVNC (e.g. the built-in proxying and un-encrypted connections) have |
| been modified to support IPv6 in SSVNC 1.0.26. |
| |
| |
| |
| |
| |
| |
| Contributions: |
| |
| Q-132: Thanks for your program or for your help! Can I make a |
| donation? |
| |
| Please do (any amount is appreciated; very few have donated) and thank |
| you for your support! Click on the PayPal button below for more info. |
| |
| [x-click-but04.gif]-Submit |
| |
| ======================================================================= |
| http://www.karlrunge.com/x11vnc/chainingssh.html: |
| |
| |
| _________________________________________________________________ |
| |
| Chaining ssh's: Note that for use of a ssh gateway and -L redirection |
| to an internal host (e.g. "-L 5900:otherhost:5900") the VNC traffic |
| inside the firewall is not encrypted and you have to manually log into |
| otherhost to start x11vnc. Kyle Amon shows a method where you chain |
| two ssh's together that encrypts all network traffic and also |
| automatically starts up x11vnc on the internal workstation: |
| #!/bin/sh |
| # |
| gateway="example.com" # or "user@example.com" |
| host="labyrinth" # or "user@hostname" |
| user="kyle" |
| |
| # Need to sleep long enough for all of the passwords and x11vnc to start up. |
| # The </dev/null below makes the vncviewer prompt for passwd via popup window. |
| # |
| (sleep 10; vncviewer -encodings "copyrect tight zrle zlib hextile" \ |
| localhost:0 </dev/null >/dev/null) & |
| |
| # Chain the vnc connection thru 2 ssh's, and connect x11vnc to user's display: |
| # |
| exec /usr/bin/ssh -t -L 5900:localhost:5900 $gateway \ |
| /usr/bin/ssh -t -L 5900:localhost:5900 $host \ |
| sudo /usr/bin/x11vnc -localhost -auth /home/$user/.Xauthority \ |
| -rfbauth .vnc/passwd -display :0 |
| |
| Also note the use of sudo(1) to switch to root so that the different |
| user's .Xauthority file can be accessed. See the visudo(8) manpage for |
| details on how to set this up (remove the sudo if you do not want to |
| do this). One can also chain together ssh's for reverse connections |
| with vncviewers using the -listen option. For this case -R would |
| replace the -L (and 5500 the 5900, see the #2 example script above). |
| If the gateway machine's sshd is configured with GatewayPorts=no (the |
| default) then the double chaining of "ssh -R ..." will be required for |
| reverse connections to work. |
| |
| ======================================================================= |
| http://www.karlrunge.com/x11vnc/miscbuild.html: |
| |
| |
| _________________________________________________________________ |
| |
| Misc. Build problems: We collect here rare build problems some users |
| have reported and the corresponding workarounds. See also the FAQ's on |
| building. |
| _________________________________________________________________ |
| |
| ENV parameter: One user had a problem where the build script below was |
| failing because his work environment had the ENV variable set to a |
| script that was resetting his PATH so that gcc could no longer be |
| found. Make sure you do not have any ENV or BASH_ENV in your |
| environment doing things like that. Typing "unset ENV", etc. before |
| configuring and building should clear it. |
| _________________________________________________________________ |
| |
| Bash xpg: One user had his bash shell compiled with |
| --enable-xpg-echo-default that causes some strange behavior with |
| things like echo "\\1 ..." the configure script executes. In |
| particular instead of getting "\1" the non-printable character "^A" is |
| produced, and causes failures at compile time like: |
| ../rfb/rfbconfig.h:9:22: warning: extra tokens at end of #ifndef directive |
| |
| The workaround is to configure like this: |
| env CONFIG_SHELL=/bin/sh /bin/sh ./configure |
| |
| i.e. avoid using the bash with the misbehavior. A bug has been filed |
| against autoconf to guard against this. |
| _________________________________________________________________ |
| |
| AIX: one user had to add the "X11.adt" package to AIX to get build |
| header files like XShm.h, etc. |
| _________________________________________________________________ |
| |
| Ubuntu Feisty Fawn 7.04: In May/2007 one user said he needed to add |
| these packages to compile x11vnc on that Linux distro and version: |
| apt-get install build-essential make bin86 libjpeg62-dev libssl-dev libxtst-d |
| ev |
| |
| Note that Ubuntu is based on Debian, so perhaps this is the list |
| needed on Debian (testing?) as well. To build in Avahi (mDNS service |
| advertising) support it would appear that libavahi-client-dev is |
| needed as well. |
| _________________________________________________________________ |
| |
| Exceedingly slow compilation: x11vnc has a couple of files which |
| contain very large "case statements" (over 100 cases) that on some |
| platforms can take a very long time to compile (in extreme cases over |
| an hour). However on 32bit Linux with intel/amd processor and gcc |
| these files usually take less than 10 seconds to compile. For 64bit |
| systems using gcc the problem appears to be much worse. |
| |
| The two files with the large number of cases, remote.c and x11vnc.c, |
| have no real need to be optimized (the code is used only very |
| infrequently). So it is fine to supply "-O0" (disables optimization) |
| to CFLAGS when compiling them. However, it is tricky with |
| autoconf/automake to do this (especially since both the compiler and |
| make versions have a big effect). |
| |
| So if the compile times are getting too long for you for these two |
| files you will need to manually change some things. First, run |
| configure and when it has finished, edit the generated file |
| x11vnc/Makefile and put these lines at the very top: |
| x11vnc-x11vnc.o : CFLAGS += -O0 |
| x11vnc-remote.o : CFLAGS += -O0 |
| |
| Those lines assume gnu make (gmake) is being used. If you are using |
| another make, say Solaris make, insert these instead: |
| x11vnc-x11vnc.o := CFLAGS += -O0 |
| x11vnc-remote.o := CFLAGS += -O0 |
| |
| You could write a build shell script that modified the Makefile this |
| way before running make. |
| |
| The "-O0" (note it is "capital Oh" followed by "zero") assumes the gcc |
| compiler. If you are using a different compiler you will need to find |
| the command line option to disable optimization, or otherwise have the |
| lines set CFLAGS to the empty string. |
| _________________________________________________________________ |
| |
| Broken Thread Local Storage on SuSE 9.2: Starting with x11vnc 0.9.8 |
| the bundled libvncserver uses the __thread keyword to make some of the |
| encodings (i.e. tight) thread safe (multiple VNC clients can be using |
| tight at the same time in x11vnc -threads mode.) Evidently on the old |
| SuSE 9.2 system the compiler does not support the thread local storage |
| properly. Here is an example build failure: |
| tight.c:1126: error: unrecognizable insn: |
| (insn:HI 11 10 13 0 (nil) (set (reg/f:SI 59) |
| (const:SI (plus:SI (symbol_ref:SI ("%lpalette")) |
| (const_int 2048 [0x800])))) -1 (nil) |
| (expr_list:REG_EQUAL (const:SI (plus:SI (symbol_ref:SI ("%lpalette")) |
| (const_int 2048 [0x800]))) |
| (nil))) |
| tight.c:1126: internal compiler error: in extract_insn, at recog.c:2175 |
| Please submit a full bug report, |
| with preprocessed source if appropriate. |
| See URL:http://www.suse.de/feedback for instructions. |
| |
| The workaround is to disable thread local storage at configure time |
| like this: |
| env CPPFLAGS="-DTLS=''" ./configure |
| |
| and then build it. |
| _________________________________________________________________ |
| |
| ======================================================================= |
| http://www.karlrunge.com/x11vnc/sunray.html: |
| |
| |
| Sun Ray Notes: |
| |
| You can run x11vnc on your (connected or disconnected) SunRay session |
| (Please remember to use settings like -wait 200, -sb 15, and not |
| running a screensaver animation (blank instead) to avoid being a |
| resource hog! x11vnc does induce a lot of memory I/O from polling the |
| X server. It also helps to have a solid background color, e.g. |
| -solid). |
| |
| News: Sun Ray Remote Control Toolkit: See the nice set of tools in the |
| Sun Ray Remote Control Toolkit that launch x11vnc automatically for |
| you for certain usage modes. |
| |
| You have to know the name of the machine your SunRay session X server |
| is running on (so you can ssh into it and start x11vnc). You also need |
| to know the X11 DISPLAY number for the session: on a SunRay it could |
| be a large number, e.g. :137, since there are many people with X |
| sessions (Xsun processes) on the same machine. If you don't know it, |
| you can get it by running who(1) in a shell on the SunRay server and |
| looking for the dtlocal entry with your username (and if you don't |
| even know which server machine has your session, you could login to |
| all possible ones looking at the who output for your username...). |
| |
| I put some code in my ~/.dtprofile script that stores $DISPLAY |
| (including the hostname) in a ~/.sunray_current file at session |
| startup (and deletes it when the X session ends) to make it easy to |
| get at the hostname and X11 display number info for my current X |
| sessions when I ssh in and am about to start x11vnc. |
| |
| SunRay Gotcha #1: Note that even though your SunRay X11 DISPLAY is |
| something like :137, x11vnc still tries for port 5900 as its listening |
| port if it can get it, in which case the VNC display (i.e. the |
| information you supply to the VNC viewer) is something like |
| sunray-server:0 (note the :0 corresponding to port 5900, it is not |
| :137). If it cannot get 5900, it tries for 5901, and so on. You can |
| also try to force the port (and thereby the VNC display) using the |
| -rfbport NNNN option. |
| |
| Especially on a busy Sun Ray server it is often difficult to find free |
| ports for both VNC and the HTTP Java applet server to listen on. This |
| script, vnc_findports may be of use for doing this automatically. It |
| suggests x11vnc command line options based on netstat output that |
| lists the occupied ports. It is even more difficult to start |
| vncserver/Xvnc on a busy Sun Ray because then 3 ports (HTTP, VNC, and |
| X11), all separated by 100 are needed! This script, findvncports may |
| be helpful as well. Both scripts start at VNC display :10 and work |
| their way up. |
| |
| SunRay Gotcha #2: If you get an error like: |
| shmget(tile) failed. |
| shmget: No space left on device |
| |
| when starting up x11vnc that most likely means all the shared memory |
| (shm) slots are filled up on your machine. The Solaris default is only |
| 100, and that can get filled up in a week or so on a SunRay server |
| with lots of users. If the shm slot is orphaned (e.g. creator process |
| dies) the slot is not reclaimed. You can view the shm slots with the |
| "ipcs -mA" command. If there are about 100 then you've probably hit |
| this problem. They can be cleaned out (by the owner or by root) using |
| the ipcrm command. I wrote a script shm_clear that finds the orphans |
| and lists or removes them. Longer term, have your SunRay sysadmin add |
| something like this to /etc/system: |
| set shmsys:shminfo_shmmax = 0x2000000 |
| set shmsys:shminfo_shmmni = 0x1000 |
| |
| SunRay Gotcha #3: Some SunRay installations have implemented |
| suspending certain applications when a SunRay session is in a |
| disconnected state (e.g. Java Badge pulled out, utdetach, etc). This |
| is a good thing because it limits hoggy or runaway apps from wasting |
| the shared CPU resource. Think how much CPU and memory I/O is wasted |
| by a bunch of Firefox windows running worthless Flash animations while |
| your session is disconnected! |
| |
| So some sites have implemented scripts to suspend (e.g. kill -STOP) |
| certain apps when your badge is removed from the SunRay terminal. When |
| you reattach, it kill -CONT them. This causes problems for viewing the |
| detached SunRay session via x11vnc: those suspended apps will not |
| respond (their windows will be blank or otherwise inactive). |
| |
| What to do? Well, since you are going to be using the application you |
| might as well unfreeze it rather than starting up a 2nd instance. Here |
| is one way to do it using the kill -CONT mechanism: |
| kill -CONT `ps -ealf | grep ' T ' | grep $LOGNAME | awk '{print $4}'` |
| |
| If you want to be a good citizen and re-freeze them before you exit |
| x11vnc this script could be of use: |
| #!/bin/sh |
| # |
| # kill -STOP/-CONT script for x11vnc (or other) SunRay usage ("freezes" |
| # certain apps from hogging resources when disconnected). |
| # |
| # Put here a pattern that matches the apps that are frozen: |
| # |
| appmatch="java_vm|jre|netscape-bin|firefox-bin|realplay|acroread|mozilla-bin" |
| |
| if [ "X$1" = "Xfreeze" ]; then |
| pkill -STOP -U $LOGNAME "$appmatch" |
| elif [ "X$1" = "Xthaw" ]; then |
| pkill -CONT -U $LOGNAME "$appmatch" |
| |
| elif [ "$RFB_MODE" = "afteraccept" -a "$RFB_STATE" = "NORMAL" ]; then |
| # a valid x11vnc login. |
| if [ "$RFB_CLIENT_COUNT" = "1" ]; then |
| # only one client present. |
| pkill -CONT -U $LOGNAME "$appmatch" |
| fi |
| elif [ "$RFB_MODE" = "gone" -a "$RFB_STATE" = "NORMAL" ]; then |
| # a valid x11vnc login. |
| if [ "$RFB_CLIENT_COUNT" = "0" ]; then |
| # last client present has just left. |
| pkill -STOP -U $LOGNAME "$appmatch" |
| fi |
| fi |
| exit 0 |
| |
| If you called the script "goodcitizen" you could type "goodcitizen |
| thaw" to unfreeze them, and then "goodcitizen freeze" to refreeze |
| them. One could also use these x11vnc options "-afteraccept |
| goodcitizen -gone goodcitizen" to do it automatically. |
| |
| SunRay Gotcha #4: Recent versions of the Sun Ray Server Software |
| SRSS (seems to be version 3.0 or 3.1) have a "misfeature" that when |
| the session is disconnected (i.e. badge/smartcard out) the screen |
| locker (xscreensaver) will freeze the X server just when the "Enter |
| Password" dialog box appears. So you cannot unlock the screen remotely |
| via x11vnc! |
| |
| Update: please see Bob Doolittle's detailed description of the this |
| issue at the bottom of this section. |
| |
| Here "freeze" means "stop other X clients from inserting keyboard and |
| mouse input and from viewing the current contents of the screen". Or |
| something like that; the upshot is x11vnc can't do its normal thing. |
| |
| There are several workarounds for this. |
| |
| 1) The easiest one by far is to put these lines in your |
| $HOME/.dtprofile file: |
| SUN_SUNRAY_UTXLOCK_PREF="/usr/openwin/bin/xlock -mode blank" |
| export SUN_SUNRAY_UTXLOCK_PREF |
| |
| One might argue that xlock isn't particularly "pretty". (Just IMHO, |
| but if something like this not being pretty actually gets in the way |
| of your work I think some introspection may be in order. :-) |
| |
| 2) The problem has been traced to the pam_sunray.so PAM module. |
| Evidently xscreensaver invokes this pam module and it communicates |
| with utsessiond who in turn instructs the Xsun server to not process |
| any synthetic mouse/keyboard input or to update the screen |
| framebuffer. It is not clear if this is by design (security?) or |
| something else. |
| |
| In any event, the problem can be avoided, somewhat drastically, by |
| commenting out the corresponding line in /etc/pam.conf: |
| #xscreensaver auth sufficient /opt/SUNWut/lib/pam_sunray.so syncondisplay |
| |
| Leave the other xscreensaver pam authentication lines unchanged. The |
| dtsession-SunRay line may also need to be commented out to avoid the |
| problem for CDE sessions. N.B. it is possible the application of a |
| SSRS patch, etc, may re-enable that /etc/pam.conf line. It may be |
| difficult to convince a sysadmin to make this change. |
| |
| 3) A more forceful way is to kill the xscreensaver process from a |
| shell prompt whenever you connect via x11vnc and the screen is in a |
| locked state: |
| pkill -U $LOGNAME '^xscreensaver$' |
| |
| And then after you are in be sure to restart it by typing something |
| like: |
| xscreensaver & |
| |
| You may want to avoid restarting it until you are about to disconnect |
| your VNC viewer (since if it locks the screen while you are working |
| you'll be stuck again). |
| |
| 3') The above idea can be done a bit more cleanly by having x11vnc do |
| it. Suppose we called the following script xss_killer: |
| #!/bin/sh |
| # |
| # xss_killer: kill xscreensaver after a valid x11vnc client logs in. |
| # Restart xscreensaver and lock it when the last client |
| # disconnects. |
| |
| PATH=/usr/openwin/bin:/usr/bin:$PATH |
| export PATH |
| |
| if [ "$RFB_MODE" = "afteraccept" -a "$RFB_STATE" = "NORMAL" ]; then |
| # a valid x11vnc login. |
| if [ "$RFB_CLIENT_COUNT" = "1" ]; then |
| # only one client present. |
| pkill -U $LOGNAME '^xscreensaver$' |
| pkill -KILL -U $LOGNAME -f xscreensaver/hacks |
| fi |
| elif [ "$RFB_MODE" = "gone" -a "$RFB_STATE" = "NORMAL" ]; then |
| # a valid x11vnc login. |
| if [ "$RFB_CLIENT_COUNT" = "0" ]; then |
| # last client present has just left. |
| xscreensaver -nosplash & |
| sleep 1 |
| xscreensaver-command -lock & |
| fi |
| fi |
| |
| Then we would run x11vnc with these options: "-afteraccept xss_killer |
| -gone xss_killer". The -afteraccept option (introduced in version 0.8) |
| is used to run a command after a vncviewer has successfully logged in |
| (note that this is a VNC login, not a Unix login, so you may not want |
| to do this if you are really paranoid...) |
| |
| Note if you use the above script and also plan to Ctrl-C (SIGINT) |
| x11vnc you have to run the xscreensaver in a new process group to |
| avoid killing it as well. One way to do this is via this kludge: |
| perl -e 'setpgrp(0,0); exec "xscreensaver -nosplash &"' |
| |
| in the above script. |
| |
| 4) There appears to be a bug in pam_sunray.so in that it doesn't seem |
| to honor the convention that, say, DISPLAY=unix:3 means to use Unix |
| sockets to connect to display 3 on the local machine (this is a bit |
| faster than TCP sockets). Rather, it thinks the display is a non-local |
| one to a machine named "unix" (that usually does not resolve to an IP |
| address). |
| |
| Amusingly, this can be used to bypass the pam_sunray.so blocking of |
| Xsun that prevents one from unlocking the screen remotely via x11vnc. |
| One could put something like this in $HOME/.dtprofile to kill any |
| existing xscreensavers and then start up a fresh xscreensaver using |
| DISPLAY=unix:N |
| # stop/kill any running xscreensavers (probably not running yet, but to be sure |
| ) |
| xscreensaver-command -exit |
| pkill -U $LOGNAME '^xscreensaver$' |
| env DISPLAY=`echo $DISPLAY | sed -e 's/^.*:/unix:/'` xscreensaver & |
| |
| |
| Important: Note that all of the above workarounds side-step the |
| pam_sunray.so PAM module in one way or another. You'll need to see if |
| that is appropriate for your site's SunRay / smartcard usage. Also, |
| these hacks may break other things and so you may want to test various |
| scenarios carefully. E.g. check corner cases like XDMCP/dtremote, |
| NSCM, etc. |
| |
| |
| Update May 2008: Here is a useful description of this issue from Bob |
| Doolittle who is a developer for Sun Ray at Sun. I don't have the time |
| to digest and distill it and then adjust the above methods to provide |
| a clearer description, so I just include below the description he sent |
| me with the hope that it will help some users: |
| |
| In SRSS 4.0 and earlier, the purpose of pam_sunray.so in the "auth" |
| PAM stack of screensavers is to enable NSCM (and, although this is |
| much less commonly used, "SC", which is configured when 3rd-party |
| software is installed to allow smartcards to be used as part of the |
| authentication process) to work. It should have no effect with |
| smartcards. Currently, however, it does block the PAM stack for all |
| sessions, which causes xscreensaver, when it locks a disconnected |
| session, to not process any mouse or keyboard events as you |
| describe (unless xscreensaver does an X server grab, however, other |
| applications should still be able to draw in the session although |
| xscreensaver may be playing tricks like putting a black window on |
| top of everything). In both of the NSCM and SC models, |
| authentication occurs in a separate session before SRSS will |
| reconnect to the user session, in which case pam_sunray.so causes |
| xscreensaver to just unlock the screen without prompting the user |
| to enter their password again. To do this, pam_sunray.so has to |
| block until the session becomes reconnected, so it can query SRSS |
| at that time to determine whether the user has already |
| authenticated or not. In SRSS 4.0 and earlier releases, |
| pam_sunray.so could have been optimized to not block smartcard |
| sessions, although since the session is disconnected this typically |
| isn't important (except in the x11vnc case, as you've observed). |
| |
| In SRSS 4.1, however, for increased security the out-of-session |
| authentication model has been extended to *all* session types, so |
| pam_sunray.so will be required in all cases unless users are |
| willing to authenticate twice upon hotdesking (e.g. when their card |
| is inserted). In future, we may do away with pam_sunray.so, and in |
| fact with any traditional screen locker in the user session, since |
| SRSS itself will be providing better security than a screen locker |
| running entirely within the user's X session is capable of |
| providing. |
| |
| Your trick of setting DISPLAY to unix:DPY will effectively disable |
| pam_sunray.so (I'm not sure I'd call that a bug - you're going out |
| of your way to do something that wouldn't occur in the normal |
| course of events, and really provides no useful value other than to |
| tickle this behavior in pam_sunray.so). This will mean that, in |
| SRSS 4.0 and earlier releases, users will be prompted for their |
| passwords twice when reconnecting to their sessions for NSCM and SC |
| session types. In 4.1, disabling pam_sunray.so in this way will |
| cause this double-authentication to occur for *all* sessions, |
| including simple smartcard sessions. Users may be willing to pay |
| that price in order to be able to use x11vnc in disconnected |
| sessions. I like this hack, personally. It's a little less |
| convenient than some of the other approaches you describe, but it's |
| lighter-weight and more secure than most of the other approaches, |
| and provides the value of being able to use x11vnc in locked |
| sessions. |
| |
| Here are some other minor notes: - I wouldn't recommend storing |
| your display in your .dtprofile, unless you're willing to live with |
| a single session at a time. Personally, I often find myself using |
| several sessions, in several FoGs, for short periods of time so |
| this would certainly break. IMO it's pretty easy to use $DISPLAY to |
| do what you want on the fly, as needed, so I don't think the price |
| of breaking multiple-session functionality would be worth the |
| convenience, to me at least. Here's some ksh/bash syntax to extract |
| the hostname and display number on the fly which you may find |
| useful: |
| HOSTNAME=${DISPLAY%:*} |
| FULLDPY=${DISPLAY#*:} |
| DPYNUM=${FULLDPY%.*} |
| |
| A final note may give you some insight into other clever hacks in |
| this area: - Check out utaction. It's a very handy little utility |
| that can be run as a daemon in the user session which will invoke a |
| specified command upon session connects and/or disconnects. |
| Personally, I start one up in my .dtprofile as follows: |
| utaction -c $HOME/.srconnectrc -d $HOME/.srdisconnectrc & |
| |
| This then allows me to construct a .srconnectrc script containing |
| useful commands I'd like to have run every time I insert my |
| smartcard, and a .srdisconnectrc script of commands to be run every |
| time I remove my smartcard (or, connect/disconnect to my session |
| via NSCM or SC). This can be used for things like notifying a chat |
| client of away status, as well as some of the hacks you've |
| described on your page such as freeze/unfreeze, or perhaps to |
| terminate an xscreensaver and start up a new one with the unix:DPY |
| $DISPLAY specification as you describe (although it probably makes |
| most sense to do this at login time, as opposed to every connect or |
| disconnect event). |
| |
| ======================================================================= |
| http://www.karlrunge.com/x11vnc/ssl.html: |
| |
| |
| _________________________________________________________________ |
| |
| Notes on x11vnc SSL Certificates and Key Management: |
| |
| The simplest scheme ("x11vnc -ssl TMP") is where x11vnc generates a |
| temporary, self-signed certificate each time (automatically using |
| openssl(1)) and the VNC viewer client accepts the certificate without |
| question (e.g. user clicks "Yes" in a dialog box. Perhaps the dialog |
| allows them to view the certificate too). Also note stunnel's default |
| is to quietly accept all certificates. |
| |
| The encryption this provides protects against all passive sniffing of |
| the VNC traffic and passwords on the network and so it is quite good, |
| but it does not prevent a Man-In-The-Middle active attack: e.g. an |
| attacker intercepts the VNC client stream and sends it his own Public |
| key for SSL negotiation (pretending to be the server). Then it makes a |
| connection to SSL x11vnc itself and forwards the data back and forth. |
| He can see all the traffic and modify it as well. |
| |
| Most people don't seem to worry about Man-In-The-Middle attacks these |
| days; they are more concerned about passive sniffing of passwords, |
| etc. Perhaps someday that will change if attack tools are used more |
| widely to perform the attack. NOTE: There are hacker tools like |
| dsniff/webmitm and cain that implement SSL Man-In-The-Middle attacks. |
| They all rely on the client not bothering to check that the cert is |
| valid. |
| |
| If you are not worried about Man-In-The-Middle attacks you do not have |
| to read the techniques described in the rest of this document. |
| |
| To prevent Man-In-The-Middle attacks, certificates must somehow be |
| verified. This requires the VNC client side have some piece of |
| information that can be used to verify the SSL x11vnc server. |
| Alternatively, although rarely done, x11vnc can verify VNC Clients' |
| certificates, see the -sslverify option that is discussed below. |
| |
| There are a number of ways to have the client authenticate the SSL |
| x11vnc server. The quickest way perhaps would be to copy (safely) the |
| certificate x11vnc prints out: |
| 26/03/2006 21:12:00 Creating a temporary, self-signed PEM certificate... |
| ... |
| -----BEGIN CERTIFICATE----- |
| MIIC4TCCAkqgAwIBAgIJAMnwCaOjvEKaMA0GCSqGSIb3DQEBBAUAMIGmMQswCQYD |
| VQQGEwJBVTEOMAwGA1UEBxMFTGludXgxITAfBgNVBAsTGGFuZ2VsYS0xMTQzNDI1 |
| NTIwLjQxMTE2OTEPMA0GA1UEChMGeDExdm5jMS4wLAYDVQQDEyV4MTF2bmMtU0VM |
| (more lines) ... |
| -----END CERTIFICATE----- |
| |
| to the client machine(s) and have the client's SSL machinery (e.g. |
| stunnel, Web Browser, or Java plugin) import the certificate. That way |
| when the connection to x11vnc is made the client can verify that is it |
| the desired server on the other side of the SSL connection. |
| |
| So, for example suppose the user is using the SSL enabled Java VNC |
| Viewer and has incorporated the x11vnc certificate into his Web |
| browser on the viewing side. If he gets a dialog that the certificate |
| is not verified he knows something is wrong. It may be a |
| Man-In-The-Middle attack, but more likely x11vnc certificate has |
| changed or expired or his browser was reinstalled and/or lost the |
| certificate, etc, etc. |
| |
| As another example, if the user was using stunnel with his VNC viewer |
| (this is mentioned in this FAQ), e.g. STUNNEL.EXE on Windows, then he |
| would have to set the "CAfile = path-to-the-cert" and "verify = 2" |
| options in the stunnel.conf file before starting up the tunnel. If a |
| x11vnc certificate cannot be verified, stunnel will drop the |
| connection (and print a failure message in its log file). |
| |
| A third example, using the VNC viewer on Unix with stunnel the wrapper |
| script can be used this way: "ss_vncviewer -verify ./x11vnc.crt |
| far-away.east:0" where ./x11vnc.crt is the copied certificate x11vnc |
| printed out. |
| |
| As fourth example, our SSVNC enhanced tightvnc viewer can also use |
| these certificate files for server authentication. You can load them |
| via the SSVNC 'Certs...' dialog and set 'ServerCert' to the |
| certificate file you safely copied there. |
| |
| Note that in principle the copying of the certificate to the client |
| machine(s) itself could be altered by a Man-In-The-Middle attack! You |
| can't win; it is very difficult to be completely secure. It is |
| unlikely the attacker could predict how you were going to send it |
| unless you had, say, done it many times before the same way. SSH is a |
| very good way to send it (but of course it too depends on public keys |
| being sent unaltered between the two machines!). |
| |
| If you are really paranoid, I'm sure you'll figure out a really good |
| way to transport the certificates. See the Certificate Authority |
| scheme below for a way to make this easier (you just have to do it |
| once). |
| |
| _________________________________________________________________ |
| |
| Saving SSL certificates and keys: |
| |
| Now, it would be very inconvenient to copy the new temporary |
| certificate every time x11vnc is run in SSL mode. So for convenience |
| there is the "SAVE" keyword to instruct x11vnc to save the certificate |
| it creates: |
| x11vnc -ssl SAVE -display :0 ... |
| |
| This behavior is now the default, you must use "TMP" for a temporary |
| one. It will save the certificate and private key in these files: |
| ~/.vnc/certs/server.crt |
| ~/.vnc/certs/server.pem |
| |
| The ".crt" file contains only the certificate and should be safely |
| copied to the VNC Viewer machine(s) that will be authenticating the |
| x11vnc server. The ".pem" file contains both the certificate and the |
| private key and should be kept secret. (If you don't like the default |
| location ~/.vnc/certs, e.g. it is on an NFS share and you are worried |
| about local network sniffing, use the -ssldir dir option to point to a |
| different directory.) |
| |
| So the next time you run "x11vnc -ssl SAVE ..." it will read the |
| server.pem file directly instead of creating a new one. |
| |
| You can manage multiple SSL x11vnc server keys in this simple way by |
| using: |
| x11vnc -ssl SAVE-key2 -display :0 ... |
| |
| etc, where you put whatever name you choose for the key after "SAVE-". |
| E.g. "-ssl SAVE-fred". |
| |
| Also, if you want to be prompted to possibly change the made up names, |
| etc. that x11vnc creates (e.g. "x11vnc-SELF-SIGNED-CERT-7762" for the |
| CommonName) for the certificates distinguished name (DN), then use |
| "x11vnc -ssl SAVE_PROMPT ...", "x11vnc -ssl SAVE_PROMPT-fred ..." etc. |
| when you create the key the first time. |
| |
| Tip: when prompting, if you choose the CommonName entry to be the full |
| internet hostname of the machine the clients will be connecting to |
| then that will avoid an annoying dialog box in their Web browsers that |
| warn that the CommonName doesn't match the hostname. |
| |
| _________________________________________________________________ |
| |
| Passphrases for server keys: |
| |
| Well, since now with the "SAVE" keyword the certificate and key will |
| be longer lived, one can next worry about somebody stealing the |
| private key and pretending to be the x11vnc server! How to guard |
| against this? |
| |
| The first is that the file is created with perms 600 (i.e. -rw-------) |
| to make it harder for an untrusted user to copy the file. A better way |
| is to also encrypt the private key with a passphrase. You are prompted |
| whether you want to do this or not when the key is first created under |
| "-ssl SAVE" mode ("Protect key with a passphrase? y/n"). It is |
| suggested that you use a passphrase. The inconvenience is every time |
| you run "x11vnc -ssl SAVE ..." you will need to supply the passphrase |
| to access the private key: |
| 06/04/2006 11:39:11 using PEM /home/runge/.vnc/certs/server.pem 0.000s |
| |
| A passphrase is needed to unlock an OpenSSL private key (PEM file). |
| Enter passphrase> |
| |
| before x11vnc can continue. |
| |
| _________________________________________________________________ |
| |
| Being your own Certificate Authority: |
| |
| A very sophisticated way that scales well if the number of users is |
| large is to use a Certificate Authority (CA) whose public certificate |
| is available to all of the VNC clients and whose private key has been |
| used to digitally sign the x11vnc server certificate(s). |
| |
| The idea is as follows: |
| * A special CA cert and key is generated. |
| * Its private key is always protected by a good passphrase since it |
| is only used for signing. |
| * The CA cert is (safely) distributed to all machines where VNC |
| clients will run. |
| * One or more x11vnc server certs and keys are generated. |
| * The x11vnc server cert is signed with the CA private key. |
| * x11vnc is run using the server key. (e.g. "-ssl SAVE") |
| * VNC clients (viewers) can now authenticate the x11vnc server |
| because they have the CA certificate. |
| |
| The advantage is the CA cert only needs to be distributed once to the |
| various machines, that can be done even before x11vnc server certs are |
| generated. |
| |
| As above, it is important the CA private key and the x11vnc server key |
| are kept secret, otherwise someone could steal them and pretend to be |
| the CA or the x11vnc server if they copied the key. It is recommended |
| that the x11vnc server keys are also protected via a passphrase (see |
| the previous section). |
| |
| Optionally, VNC viewer certs and keys could also be generated to |
| enable the x11vnc server to authenticate each client. This is not |
| normally done (usually a simple viewer password scheme is used), but |
| this can be useful in some situations. These optional steps go like |
| this: |
| * One or more VNC client certs and keys are generated. |
| * These VNC client certs are signed with the CA private key. |
| * The VNC client certs+keys are safely distributed to the |
| corresponding client machines. |
| * x11vnc is told to verify clients by using the CA cert. (e.g. |
| "-sslverify CA") |
| * When VNC clients (viewers) connect, they must authenticate |
| themselves to x11vnc by using their client key. |
| |
| Again, it is a good idea if the client private keys are protected with |
| a passphrase, otherwise if stolen they could be used to gain access to |
| the x11vnc server. Once distributed to the client machines, there is |
| no need to keep the client key on the CA machine that generated and |
| signed it. You can keep the client certs if you like because they are |
| public. |
| |
| _________________________________________________________________ |
| |
| How to do the above CA steps with x11vnc: |
| |
| Some utility commands are provided to ease the cert+key creation, |
| signing, and management: -sslGenCA, -sslGenCert, -sslDelCert, |
| -sslEncKey, -sslCertInfo. They basically run the openssl(1) command |
| for you to manage the certs/keys. It is required that openssl(1) is |
| installed on the machine and available in PATH. All commands can be |
| pointed to an alternate toplevel certificate directory via the -ssldir |
| option if you don't want to use the default ~/.vnc/certs. |
| |
| 1) To generate your Certificate Authority (CA) cert and key run this: |
| x11vnc -sslGenCA |
| |
| Follow the prompts, you can modify any informational strings you care |
| to. You will also be required to encrypt the CA private key with a |
| passphrase. This generates these files: |
| ~/.vnc/certs/CA/cacert.pem (the CA public certificate) |
| ~/.vnc/certs/CA/private/cakey.pem (the encrypted CA private key) |
| |
| If you want to use a different directory use -ssldir It must supplied |
| with all subsequent SSL utility options to point them to the correct |
| directory. |
| |
| 2) To generate a signed x11vnc server cert and key run this: |
| x11vnc -sslGenCert server |
| |
| As with the CA generation, follow the prompts and you can modify any |
| informational strings that you care to. This will create the files: |
| ~/.vnc/certs/server.crt (the server public certificate) |
| ~/.vnc/certs/server.pem (the server private key + public cert) |
| |
| It is recommended to protect the server private key with a passphrase |
| (you will be prompted whether you want to). You will need to provide |
| it whenever you start x11vnc using this key. |
| |
| 3) Start up x11vnc using this server key: |
| x11vnc -ssl SAVE -display :0 ... |
| |
| (SAVE corresponds to server.pem, see -sslGenCert server somename info |
| on creating additional server keys, server-somename.crt ...) |
| |
| 4) Next, safely copy the CA certificate to the VNC viewer (client) |
| machine(s). Perhaps: |
| scp ~/.vnc/CA/cacert.pem clientmachine:. |
| |
| 5) Then the tricky part, make it so the SSL VNC Viewer uses this |
| certificate! There are a number of ways this might be done, it depends |
| on what your client and/or SSL tunnel is. Some examples: |
| |
| For the SSL Java VNC viewer supplied with x11vnc in |
| classes/ssl/VncViewer.jar or classes/ssl/SignedVncViewer.jar: |
| * Import the cacert.pem cert into your Web Browser (e.g. Edit -> |
| Preferences -> Privacy & Security -> Manage Certificates -> |
| WebSites -> Import) |
| * Or Import the cacert.pem cert into your Java Plugin (e.g. run |
| ControlPanel, then Security -> Certificates -> Secure Site -> |
| Import) |
| |
| When importing, one would give the browser/java-plugin the path to the |
| copied cacert.pem file in some dialog. Note that the Web browser or |
| Java plugin is used for the server authentication. If the user gets a |
| "Site not verified" message while connecting he should investigate |
| further. |
| |
| For the use of stunnel (e.g. on Windows) one would add this to the |
| stunnel.conf: |
| # stunnel.conf: |
| client = yes |
| options = ALL |
| CAfile = /path/to/cacert.pem # or maybe C:\path\to\cacert.pem |
| [myvncssl] |
| accept = 5901 |
| connect = far-away.east:5900 |
| |
| (then point the VNC viewer to localhost:1). |
| |
| Here is an example for the Unix stunnel wrapper script ss_vncviewer in |
| our SSVNC package: |
| ss_vncviewer -verify ./cacert.pem far-away.east:0 |
| |
| Our SSVNC enhanced tightvnc viewer GUI can also use the certificate |
| file for server authentication. You can load it via the SSVNC |
| 'Certs...' dialog and set 'ServerCert' to the cacert.pem file you |
| safely copied there. |
| |
| _________________________________________________________________ |
| |
| Tricks for server keys: |
| |
| To create additional x11vnc server keys do something like this: |
| x11vnc -sslGenCert server myotherkey |
| |
| and use it this way: |
| x11vnc -ssl SAVE-myotherkey ... |
| |
| The files will be ~/.vnc/certs/server-myotherkey.{crt,pem} |
| |
| You can also create a self-signed server key: |
| x11vnc -sslGenCert server self:third_key |
| |
| and use it this way: |
| x11vnc -ssl SAVE-self:third_key ... |
| |
| This key is not signed by your CA. This can be handy to have a key set |
| separate from your CA when you do not want to create a 2nd CA |
| cert+key. |
| |
| _________________________________________________________________ |
| |
| Using external CA's: |
| |
| You don't have to use your own CA cert+key, you can use a third |
| party's instead. Perhaps you have a company-wide CA or you can even |
| have your x11vnc certificate signed by a professional CA (e.g. |
| www.thawte.com or www.verisign.com or perhaps the free certificate |
| service www.startcom.org or www.cacert.org). |
| |
| The advantage to doing this is that the VNC client machines will |
| already have the CA certificates installed and you don't have to |
| install it on each machine. |
| |
| To generate an x11vnc server cert+key this way you should generate a |
| "request" for a certicate signing something like this (we use the name |
| "external" in this example, it could be anything you want): |
| x11vnc -sslGenCert server req:external |
| |
| This will create the request file: |
| ~/.vnc/certs/server-req:external.req |
| |
| Which you should send to the external CA. When you get the signed |
| certificate back from them, save it in the file: |
| ~/.vnc/certs/server-req:external.crt |
| |
| and create the .pem this way: |
| mv ~/.vnc/certs/server-req:external.key ~/.vnc/certs/server-req:external. |
| pem |
| chmod 600 ~/.vnc/certs/server-req:external.pem |
| cat ~/.vnc/certs/server-req:external.crt >> ~/.vnc/certs/server-req:external. |
| pem |
| |
| You also rename the two files (.crt and .pem) to have a shorter |
| basename if you like. E.g.: |
| mv ~/.vnc/certs/server-req:external.pem ~/.vnc/certs/server-ext.pem |
| mv ~/.vnc/certs/server-req:external.crt ~/.vnc/certs/server-ext.crt |
| |
| and the use via "x11vnc -ssl SAVE-ext ...", etc. |
| |
| On the viewer side make sure the external CA's certificate is |
| installed an available for the VNC viewer software you plan to use. |
| |
| _________________________________________________________________ |
| |
| Using Client Keys for Authentication: |
| |
| You can optionally create certs+keys for your VNC client machines as |
| well. After distributing them to the client machines you can have |
| x11vnc verify the clients using SSL. Here is how to do this: |
| |
| x11vnc -sslGenCert client dilbert |
| x11vnc -sslGenCert client wally |
| x11vnc -sslGenCert client alice |
| ... |
| |
| As usual, follow the prompts if you want to change any of the info |
| field values. As always, it is a good idea (although inconvenient) to |
| protect the private keys with a passphrase. These files are created: |
| ~/.vnc/certs/clients/dilbert.crt |
| ~/.vnc/certs/clients/dilbert.pem |
| ... |
| |
| Note that these are kept in a clients subdirectory. |
| |
| Next, safely copy the .pem files to each corresponding client machine |
| and incorporate them into the VNC viewer / SSL software (see the ideas |
| mentioned above for the CA and server keys). The only difference is |
| these certificates might be referred to as "My Certificates" or |
| "Client Certificates". They are used for client authentication (which |
| is relatively rare for SSL). |
| |
| After copying them you can delete the clients/*.pem files for extra |
| safety because the private keys are not needed by the x11vnc server. |
| You don't really need the clients/*.crt files either (because they |
| have been signed by the CA). But they could come in handy for tracking |
| or troubleshooting, etc. |
| |
| Now start up x11vnc and instruct it to verify connecting clients via |
| SSL and the CA cert: |
| x11vnc -ssl SAVE -sslverify CA |
| |
| The "CA" special token instructs x11vnc to use its CA signed certs for |
| verification. |
| |
| For arbitrary self-signed client certificates (no CA) it might be |
| something like this: |
| x11vnc -ssl SAVE -sslverify path/to/client.crt |
| x11vnc -ssl SAVE -sslverify path/to/client-hash-dir |
| x11vnc -ssl SAVE -sslverify path/to/certs.txt |
| |
| Where client.crt would be an individual client certificate; |
| client-hash-dir a directory of file names based on md5 hashes of the |
| certs (see -sslverify); and certs.txt signifies a single file full of |
| client certificates. |
| |
| Finally, connect with your VNC viewer using the key. Here is an |
| example for the Unix stunnel wrapper script ss_vncviewer: using client |
| authentication (and the standard server authentication with the CA |
| cert): |
| ss_vncviewer -mycert ./dilbert.pem -verify ./cacert.pem far-away.east:0 |
| |
| Our SSVNC enhanced tightvnc viewer can also use these openssl .pem |
| files (you can load them via Certs... -> MyCert dialog). |
| |
| It is also possible to use -sslverify on a per-client key basis, and |
| also using self-signed client keys (x11vnc -sslGenCert client |
| self:dilbert) |
| |
| Now a tricky part is to get Web browsers or Java Runtime to import and |
| use the openssl .pem cert+key files. See the next paragraph on how to |
| convert them to pkcs12 format. If you find a robust way to import them |
| and and get them to use the cert please let us know! |
| |
| Here is how to convert our openssl crt/pem files to pkcs12 format |
| (contains both the client certificate and key) that can be read by Web |
| browsers and Java for use in client authentication: |
| openssl pkcs12 -export -in mycert.crt -inkey mycert.pem -out mycert.p12 |
| |
| it will ask for a passphrase to protect mycert.p12. Some software |
| (e.g. Java ControlPanel) may require a non-empty passphrase. Actually, |
| since our .pem contains both the certificate and private key, you |
| could just supply it for the -in and remove the -inkey option. It |
| appears that for certificates only importing, our .crt file is |
| sufficient and can be read by Mozilla/Firefox and Java... |
| |
| If you have trouble getting your Java Runtime to import and use the |
| cert+key, there is a workaround for the SSL-enabled Java applet. On |
| the Web browser URL that retrieves the VNC applet, simply add a |
| "/?oneTimeKey=..." applet parameter (see ssl-portal for more details |
| on applet parameters; you don't need to do the full portal setup |
| though). The value of the oneTimeKey will be the very long string that |
| is output of the onetimekey program found in the classes/ssl x11vnc |
| directory. Or you can set oneTimeKey=PROMPT in which case the applet |
| will ask you to paste in the long string. These scheme is pretty ugly, |
| but it works. A nice application of it is to make one time keys for |
| users that have already logged into a secure HTTPS site via password. |
| A cgi program then makes a one time key for the logged in user to use: |
| it is passed back over HTTPS as the applet parameter in the URL and so |
| cannot be sniffed. x11vnc is run to use that key via -sslverify. |
| |
| Update: as of Apr 2007 in the 0.9.1 x11vnc tarball there is a new |
| option setting "-users sslpeer=" that will do a switch user much like |
| -unixpw does, but this time using the emailAddress field of the |
| Certificate subject of the verified Client. This mode requires |
| -sslverify turned on to verify the clients via SSL. This mode can be |
| useful in situations using -create or -svc where a new X server needs |
| to be started up as the authenticated user (but unlike in -unixpw |
| mode, the unix username is not obviously known). |
| |
| _________________________________________________________________ |
| |
| Revoking Certificates: |
| |
| A large, scaled-up installation may benefit from being able to revoke |
| certificates (e.g. suppose a user's laptop with a vnc client or server |
| key is compromised.) You can use this option with x11vnc: -sslCRL. See |
| the info at that link for a guide on what openssl(1) commands you will |
| need to run to revoke a certificate. |
| |
| _________________________________________________________________ |
| |
| Additional utlities: |
| |
| You can get information about your keys via -sslCertInfo. These lists |
| all your keys: |
| x11vnc -sslCertInfo list |
| x11vnc -sslCertInfo ll |
| |
| (the latter is long format). |
| |
| These print long output, including the public certificate, for |
| individual keys: |
| x11vnc -sslCertInfo server |
| x11vnc -sslCertInfo dilbert |
| x11vnc -sslCertInfo all (every key, very long) |
| |
| If you want to add a protecting passphrase to a key originally created |
| without one: |
| x11vnc -sslEncKey SAVE |
| x11vnc -sslEncKey SAVE-fred |
| |
| To delete a cert+key: |
| x11vnc -sslDelCert SAVE |
| x11vnc -sslDelCert SAVE-fred |
| x11vnc -sslDelCert wally |
| |
| (but rm(1) will be just as effective). |
| |
| _________________________________________________________________ |
| |
| Chained Certificates: |
| |
| There is increasing interest in using chained CA's instead of a single |
| CA. The merits of using chained CA's are not described here besides to |
| say its use may make some things easier when a certificate needs to be |
| revoked. |
| |
| x11vnc supports chained CA certificates. We describe a basic use case |
| here. |
| |
| Background: Of course the most straight forward way to use SSL with |
| x11vnc is to use no CA at all (see above): a self-signed certificate |
| and key is used and its certificate needs to be safely copied to the |
| client side. This is basically the same as the SSH style of managing |
| keys. Next level up, one can use a single CA to sign server keys: then |
| only the CA's certificate needs to be safely copied to the client |
| side, this can happen even before any server certs are created (again, |
| see all of the discussion above.) |
| |
| With a certificate chain there are two or more CA's involved. Perhaps |
| it looks like this: |
| root_CA ---> intermediate_CA ---> server_cert |
| |
| Where the arrow basically means "signs". |
| |
| In this usage mode the client (viewer-side) will have root_CA's |
| certificate available for verifying (and nothing else.) If the viewer |
| only received server_cert's certificate, it would not have enough info |
| to verify the server. The client needs to have intermediate_CA's cert |
| as well. The way to do this with x11vnc (i.e. an OpenSSL using app) is |
| to concatenate the server_cert's pem and the intermediate_CA's |
| certificate together. |
| |
| For example, suppose the file intermediate_CA.crt had |
| intermediate_CA's certificate. And suppose the file server_cert.pem |
| had the server's certificate and private key pair as described above |
| on this page. We need to do this: |
| cat intermediate_CA.crt >> server_cert.pem |
| |
| (Note: the order of the items inside the file matters; intermediate_CA |
| must be after the server key and cert) and then we run x11vnc like |
| this: |
| x11vnc -ssl ./server_cert.pem ... |
| |
| Then, on the VNC viewer client side, the viewer authenticates the |
| x11vnc server by using root_CA's certificate. Suppose that is in a |
| file named root_CA.crt, then using the SSVNC wrapper script |
| ss_vncviewer (which is also included in the SSVNC package) as our |
| example, we have: |
| ss_vncviewer -verify ./root_CA.crt hostname:0 |
| |
| (where "hostname" is the machine where x11vnc is running.) One could |
| also use the SSVNC GUI setting Certs -> ServerCert to the root_CA.crt |
| file. Any other SSL enabled VNC viewer would use root_CA.crt in a |
| similar way. |
| _________________________________________________________________ |
| |
| Creating Chained Certificates: |
| |
| Here is a fun example using VeriSign's "Trial Certificate" program. |
| Note that VeriSign has a Root CA and also an Intermediate CA and uses |
| the latter to sign customers certificates. So this provides an easy |
| way to test out the chained certificates mechanism with x11vnc. |
| |
| First we created a test x11vnc server key: |
| openssl genrsa -out V1.key 1024 |
| |
| then we created a certificate signing request (CSR) for it: |
| openssl req -new -key V1.key -out V1.csr |
| |
| (we followed the prompts and supplied information for the various |
| fields.) |
| |
| Then we went to VeriSign's page http://www.verisign.com/ssl/index.html |
| and clicked on "FREE TRIAL" (the certificate is good for 14 days.) We |
| filled in the forms and got to the point where it asked for the CSR |
| and so we pasted in the contents of the above V1.csr file. Then, after |
| a few more steps, VeriSign signed and emailed us our certificate. |
| |
| The VeriSign Trial certificates were found here: |
| http://www.verisign.com/support/verisign-intermediate-ca/Trial_Secure_Server_ |
| Root/index.html |
| http://www.verisign.com/support/verisign-intermediate-ca/trial-secure-server- |
| intermediate/index.html |
| |
| The former was pasted into a file V-Root.crt and the latter was pasted |
| into V-Intermediate.crt |
| |
| We pasted our Trial certificate that VeriSign signed and emailed to us |
| into a file named V1.crt and then we typed: |
| cat V1.key V1.crt > V1.pem |
| cat V1.pem V-Intermediate.crt > V1-combined.pem |
| chmod 600 V1.pem V1-combined.pem |
| |
| So now the file V1-combined.pem has our private key and (VeriSign |
| signed) certificate and VeriSign's Trial Intermediate certificate. |
| |
| Next, we start x11vnc: |
| x11vnc -ssl ./V1-combined.pem ... |
| |
| and finally, on the viewer side (SSVNC wrapper script example): |
| ss_vncviewer -verify ./V-Root.crt hostname:0 |
| |
| One will find that only that combination of certs and keys will work, |
| i.e. allow the SSL connection to be established. Every other |
| combination we tried failed (note that ss_vncviewer uses the external |
| stunnel command to handle the SSL so we are really testing stunnel's |
| SSL implementation on the viewer side); and so the system works as |
| expected. |
| _________________________________________________________________ |
| |
| VNC Client Authentication using Certificate Chains: |
| |
| Now, going the other way around with the client authenticating himself |
| via this chain of SSL certificates, x11vnc is run this way: |
| x11vnc -ssl SAVE -sslverify ./V-Root.crt ... |
| |
| (note since the server must always supply a cert, we use its normal |
| self-signed, etc., one via "-ssl SAVE" and use the VeriSign root cert |
| for client authentication via -sslverify. The viewer must now supply |
| the combined certificates, e.g.: |
| ss_vncviewer -mycert ./V1-combined.pem hostname:0 |
| _________________________________________________________________ |
| |
| Using OpenSSL and x11vnc to create Certificate Chains: |
| |
| Although the x11vnc CA mechanism (-sslGenCA and -sslGenCert; see |
| above) was designed to only handle a single root CA (to sign server |
| and/or client certs) it can be coerced into creating a certificate |
| chain by way of an extra openssl(1) command. |
| |
| We will first create two CA's via -sslGenCA; then use one of these CA |
| to sign the other; create a new (non-CA) server cert; and append the |
| intermediate CA's cert to the server cert to have everything needed in |
| the one file. |
| |
| Here are the commands we ran to do what the previous paragraph |
| outlines. |
| |
| First we create the two CA's, called CA_root and CA_Intermediate here, |
| in separate directories via x11vnc: |
| x11vnc -ssldir ~/CA_Root -sslGenCA |
| (follow the prompts, we included "CA_Root", e.g. Common Name, to aid ident |
| ifying it) |
| |
| x11vnc -ssldir ~/CA_Intermediate -sslGenCA |
| (follow the prompts, we included "CA_Intermediate", e.g. Common Name, to a |
| id identifying it) |
| |
| Next backup CA_Intermediate's cert and then sign it with CA_Root: |
| mv ~/CA_Intermediate/CA/cacert.pem ~/CA_Intermediate/CA/cacert.pem.ORIG |
| cd ~/CA_Root |
| openssl ca -config ./CA/ssl.cnf -policy policy_anything -extensions v3_ca -no |
| text -ss_cert ~/CA_Intermediate/CA/cacert.pem.ORIG -out ~/CA_Intermediate/CA/ca |
| cert.pem |
| |
| Note that it is required to cd to the ~/CA_Root directory and run the |
| openssl command from there. |
| |
| You can print out info about the cert you just modified by: |
| openssl x509 -noout -text -in ~/CA_Intermediate/CA/cacert.pem |
| |
| Now we create an x11vnc server cert named "test_chain" that is signed |
| by CA_Intermediate: |
| x11vnc -ssldir ~/CA_Intermediate -sslGenCert server test_chain |
| (follow the prompts) |
| |
| You can print out information about this server cert just created via |
| this command: |
| x11vnc -ssldir ~/CA_Intermediate -sslCertInfo SAVE-test_chain |
| |
| This will tell you the full path to the server certificate, which is |
| needed because we need to manually append the CA_Intermediate cert for |
| the chain to work: |
| cat ~/CA_Intermediate/CA/cacert.pem >> ~/CA_Intermediate/server-test_chain.pe |
| m |
| |
| Now we are finally ready to use it. We can run x11vnc using this |
| server cert+key by either this command: |
| x11vnc -ssldir ~/CA_Intermediate -ssl SAVE-test_chain ... |
| |
| or this command: |
| x11vnc -ssl ~/CA_Intermediate/server-test_chain.pem ... |
| |
| since they are equivalent (both load the same pem file.) |
| |
| Finally we connect via VNC viewer that uses CA_Root to verify the |
| server. As before we use ss_vncviewer: |
| ss_vncviewer -verify ~/CA_Root/CA/cacert.pem hostname:0 |
| |
| Client Certificates (see above) work in a similar manner. |
| |
| So although it is a little awkward with the extra steps (e.g. |
| appending the CA_Intermediate cert) it is possible. If you want to do |
| this entirely with openssl(1) you will have to learn the openssl |
| commands corresponding to -genCA and -genCert. You may be able to find |
| guides on the Internet to do this. Starting with x11vnc 0.9.10, you |
| can have it print out the wrapper scripts it uses via: -sslScripts |
| (you will still need to fill in a few pieces of information; ask if it |
| is not clear from the source code.) |
| |
| _________________________________________________________________ |
| |
| More info: |
| |
| See also this article for some some general info and examples using |
| stunnel and openssl on Windows with VNC. Also |
| http://www.stunnel.org/faq/certs.html is a very good source of |
| information on SSL certificate creation and management. |
| |
| ======================================================================= |
| http://www.karlrunge.com/x11vnc/ssl-portal.html: |
| |
| |
| _________________________________________________________________ |
| |
| Using Apache as an SSL Gateway to multiple x11vnc servers inside a |
| firewall: |
| |
| Background: |
| |
| The typical way to allow access to x11vnc (or any other VNC server) |
| running on multiple workstations inside a firewall is via SSH. The |
| user somewhere out on the Internet logs in to the SSH gateway machine |
| and uses port forwarding (e.g. ssh -t -L 5900:myworkstation:5900 |
| user@gateway) to set up the encrypted channel that VNC is then |
| tunneled through. Next he starts up the VNC viewer on the machine |
| where he is sitting directed to the local tunnel port (e.g. |
| localhost:0). |
| |
| The SSH scheme is nice because it is a widely used and well tested |
| login technique for users connecting to machines inside their company |
| or home firewall. For VNC access it is a bit awkward, however, because |
| SSH needs to be installed on the Viewer machine and the user usually |
| has to rig up his own port redirection plumbing (however, see our |
| other tool). |
| |
| Also, some users have restrictive work environments where SSH and |
| similar applications are prohibited (i.e. only outgoing connections to |
| standard WWW ports from a browser are allowed, perhaps mediated by a |
| proxy server). These users have successfully used the method described |
| here for remote access. |
| |
| With the SSL support in x11vnc and the SSL enabled Java VNC viewer |
| applet, a convenient and secure alternative exists that uses the |
| Apache webserver as a gateway. The idea is that the company or home |
| internet connection is already running apache as a web server (either |
| SSL or non-SSL) and we add to it the ability to act as a gateway for |
| SSL VNC connections. The only thing needed on the Viewer side is a |
| Java enabled Web Browser: the user simply enters a URL that starts the |
| entire VNC connection process. No VNC or SSH specific software needs |
| to be installed on the viewer side machine. |
| |
| The stunnel VNC viewer stunnel wrapper script provided (ss_vncviewer) |
| can also take advantage of the method described here with its -proxy |
| option. |
| |
| _________________________________________________________________ |
| |
| Simpler Solutions: This apache SSL VNC portal solution may be too much |
| for you. It is mainly intended for automatically redirecting to |
| MULTIPLE workstations inside the firewall. If you only have one or two |
| inside machines that you want to access, the method described here is |
| overly complicated! See below for some simpler (and still non-SSH) |
| encrypted setups. |
| |
| Also see the recent (Mar/2010) desktop.cgi x11vnc desktop web login |
| CGI script that achieves much of what the method describes here |
| (especially if its 'port redirection' feature is enabled.) |
| _________________________________________________________________ |
| |
| |
| |
| There are numerous ways to achieve this with Apache. We present one of |
| the simplest ones here. |
| |
| Important: these sorts of schemes allow incoming connections from |
| anywhere on the Internet to fixed ports on machines inside the |
| firewall. Care must be taken to implement and test thoroughly. If one |
| is paranoid one can (and should) add extra layers of protection. (e.g. |
| extra passwords, packet filtering, SSL certificate verification, etc). |
| |
| Also, it is easy to miss the point that unless precautions are taken |
| to verify SSL Certificates, then the VNC Viewer is vulnerable to |
| man-in-the-middle attacks (but not to the more common passive sniffing |
| attacks). Note that there are hacker tools like dsniff/webmitm and |
| cain that implement SSL Man-In-The-Middle attacks. They rely on the |
| client not bothering to check the cert. |
| _________________________________________________________________ |
| |
| The Holy Grail: a single https port (443) |
| |
| Before we discuss the self-contained apache examples here, we want to |
| mention that many x11vnc users who read this page and implement the |
| apache SSL VNC portal ask for something that (so far) seems difficult |
| or impossible to do entirely inside apache: |
| * A single port, 443 (the default https:// port), is open to the |
| Internet |
| * It is HTTPS/SSL encrypted |
| * It handles both VNC traffic and Java VNC Applet downloads. |
| * And the server can also serve normal HTTPS webpages, CGI, etc. |
| |
| It is the last item that makes it tricky (otherwise the method |
| described on this page will work). If you are interested in such a |
| solution and are willing to run a separate helper program |
| (connect_switch) look here. Also, see this apache patch. |
| _________________________________________________________________ |
| |
| Example: |
| |
| The scheme described here sets up apache on the firewall/gateway as a |
| regular Web proxy into the intranet and allows connections to a single |
| fixed port on a limited set of machines. |
| |
| The configuration described in this section does not use the mod_ssl |
| apache module (the optional configuration described in the section |
| "Downloading the Java applet to the browser via HTTPS" does take |
| advantage of mod_ssl) |
| |
| In this example suppose the gateway machine running apache is named |
| "www.gateway.east" (e.g. it may also provide normal web service). We |
| also choose the Internet-facing port for this VNC service to be port |
| 563. One could choose any port, including the default HTTP port 80. |
| |
| Detail: We choose 563 because it is the rarely used SNEWS port that is |
| often allowed by Web proxies for the CONNECT method. The idea is the |
| user may be coming out of another firewall using a proxy (not the one |
| we describe here, that is, the case when two proxies are involved, |
| e.g. one at work and another Apache (described here) at home |
| redirecting into our firewall; the "double proxy" or "double firewall" |
| problem). Using port 563 simplifies things because CONNECT's to it are |
| usually allowed by default. |
| |
| We also assume all of the x11vnc servers on the internal machines are |
| all listening on port 5915 ("-rfbport 5915") instead of the default |
| 5900. This is to limit any unintended proxy redirections to a lesser |
| used port, and also to stay out of the way of normal VNC servers on |
| the same machines. One could obviously implement a scheme that handles |
| different ports, but we just discuss this simple setup here. |
| |
| So we basically assume x11vnc has been started this way on all of the |
| workstations to be granted VNC access: |
| x11vnc -ssl SAVE -http -display :0 -forever -rfbauth ~/.vnc/passwd -rfbport 5 |
| 915 |
| |
| i.e. we force SSL VNC connections, port 5915, serve the Java VNC |
| viewer applet, and require a VNC password (another option would be |
| -unixpw). The above command could also be run out of inetd(8). It can |
| also be used to autodetect the user's display and Xauthority data. |
| |
| |
| These sections are added to the httpd.conf apache configuration file |
| on www.gateway.east: |
| |
| # In the global section you need to enable these modules. |
| # Note that the ORDER MATTERS! mod_rewrite must be before mod_proxy |
| # (so that we can check the allowed host list via rewrite) |
| # |
| LoadModule rewrite_module modules/mod_rewrite.so |
| LoadModule proxy_module modules/mod_proxy.so |
| LoadModule proxy_connect_module modules/mod_proxy_connect.so |
| LoadModule proxy_ftp_module modules/mod_proxy_ftp.so |
| LoadModule proxy_http_module modules/mod_proxy_http.so |
| <IfDefine SSL> |
| LoadModule ssl_module modules/mod_ssl.so |
| </IfDefine> |
| |
| |
| # Near the bottom of httpd.conf you put the port 563 virtual host: |
| |
| Listen 563 |
| |
| <VirtualHost *:563> |
| |
| # Allow proxy CONNECT requests *only* to port 5915. |
| # If the machines use different ports, e.g. 5916 list them here as well: |
| # |
| ProxyRequests On |
| AllowCONNECT 5915 |
| |
| RewriteEngine On |
| |
| # Convenience rules to expand applet parameters. These do not have a traili |
| ng "/" |
| # |
| # /vnc for http jar file downloading: |
| # |
| RewriteRule /vnc/([^/]+)$ /vnc/$1/index.vnc?CONNECT=$1+5915&PO |
| RT=563&urlPrefix=_2F_vnc_2F_$1 [R,NE,L] |
| RewriteRule /vnc/trust/([^/]+)$ /vnc/$1/index.vnc?CONNECT=$1+5915&PO |
| RT=563&urlPrefix=_2F_vnc_2F_$1&trustAllVncCerts=yes [R,NE,L] |
| RewriteRule /vnc/proxy/([^/]+)$ /vnc/$1/proxy.vnc?CONNECT=$1+5915&PO |
| RT=563&urlPrefix=_2F_vnc_2F_$1&forceProxy=yes [R,NE,L] |
| RewriteRule /vnc/trust/proxy/([^/]+)$ /vnc/$1/proxy.vnc?CONNECT=$1+5915&PO |
| RT=563&urlPrefix=_2F_vnc_2F_$1&forceProxy=yes&trustAllVncCerts=yes [R,NE,L] |
| |
| # Read in the allowed host to vnc display mapping file. It looks like: |
| # |
| # host1 15 |
| # host2 15 |
| # ... |
| # |
| # the display "15" means 5815 for http applet download, 5915 for SSL vnc. |
| # |
| RewriteMap vnchosts txt:/dist/apache/conf/vnc.hosts |
| |
| # Proxy: check for the CONNECT hostname and port being in the vnc.hosts list |
| . |
| # |
| RewriteCond %{THE_REQUEST} ^CONNECT [NC] |
| RewriteCond %{REQUEST_URI} ^(.*):(.*)$ |
| RewriteCond ${vnchosts:%1|NOTFOUND} NOTFOUND |
| RewriteRule ^.*$ /VNCFAIL [F,L] |
| |
| RewriteCond %{THE_REQUEST} ^CONNECT [NC] |
| RewriteCond %{REQUEST_URI} ^(.*):(.*)$ |
| RewriteCond 59${vnchosts:%1}=%2 !^(.*)=(\1)$ |
| RewriteRule ^.*$ /VNCFAIL [F,L] |
| |
| |
| # Remap /vnc to the proxy http download (e.g. http://host:5815) |
| # |
| # First, fail if it starts with the string /vnc0: |
| # |
| RewriteRule ^/vnc0.* /VNCFAIL [F,L] |
| # |
| # Next, map the prefix to /vnc0/host:protocol:port |
| # |
| RewriteRule ^/vnc/([^/]+)/(.*) /vnc0/$1:http:58${vnchosts:$1|NOTFOUND}/$2 |
| [NE] |
| # |
| # Drop any not found: |
| # |
| RewriteRule ^/vnc0.*NOTFOUND.* /VNCFAIL [F,L] |
| |
| # Construct the proxy URL and retrieve it: |
| # |
| RewriteRule ^/vnc0/([^/]+):([^/]+):([^/]+)/(.*) $2://$1:$3/$4 [P,NE,L] |
| |
| </VirtualHost> |
| |
| Then restart apache (perhaps: "apachectl stop; apachectl start"). |
| |
| Note that the listing of allowed internal workstations is done in an |
| external file (/dist/apache/conf/vnc.hosts in the example above), the |
| format is like this: |
| # allowed vnc hosts file: |
| hostname1 15 |
| hostname2 15 |
| ... |
| |
| You list the hostname and the VNC display (always 15 in our example). |
| Only to these hosts will the external VNC viewers be able to connect |
| to (via the HTTP CONNECT method). |
| |
| The above setup requires mod_rewrite and mod_proxy be enabled in the |
| apache web server. In this example they are loaded as modules (and |
| note that mod_rewrite must be listed before mod_proxy); |
| |
| The user at the Java enabled Web browser would simply enter this URL |
| into the browser: |
| http://www.gateway.east:563/vnc/host2 |
| |
| to connect to internal workstation host2, etc. |
| |
| Important: do not put a trailing "/" on the URL, since that will |
| defeat the RewriteRules that look for the hostname at the very end. |
| |
| There will be a number of SSL certificate, etc, dialogs he will have |
| to respond to in addition to any passwords he is required to provide |
| (this depends on how you set up user authentication for x11vnc). |
| |
| If a second Web proxy is involved (i.e. the user's browser is inside |
| another firewall and policy requires using a Web proxy server) then |
| use this URL: |
| http://www.gateway.east:563/vnc/proxy/host2 |
| |
| This will involve downloading a signed java viewer applet jar file |
| that is able to interact with the internal proxy for the VNC |
| connection. See this FAQ for more info on how this works. Note: |
| sometimes with the Proxy case if you see 'Bad Gateway' error you will |
| have to wait 10 or so seconds and then hit reload. This seems to be |
| due to having to wait for a Connection Keepalive to terminate... |
| |
| For completeness, the "trust" cases that skip a VNC certificate dialog |
| (discussed below) would be entered as: |
| http://www.gateway.east:563/vnc/trust/host2 |
| http://www.gateway.east:563/vnc/trust/proxy/host2 |
| |
| You can of course choose shorter or more easy to remember URL formats. |
| Just change the Convenience RewriteRules in httpd.conf. |
| |
| _________________________________________________________________ |
| |
| Port Variations: |
| |
| Note that you can run this on the default HTTP port 80 instead of port |
| 563. If you do not expect to have a browser connecting from inside a |
| proxying firewall (where sometimes only connections to ports 443 and |
| 563 are allowed) this should be fine. Use "80" instead of "563" in the |
| httpd.conf config file (you may need to merge it with other default |
| port 80 things you have there). |
| |
| Then the URL's will be a bit simpler: |
| http://www.gateway.east/vnc/host2 |
| http://www.gateway.east/vnc/trust/host2 |
| |
| etc. |
| |
| Besides 80 one could use any other random port number (since there are |
| so many port scans on 80, a little obscurity might be useful). |
| |
| One option is to use port "443" (the default https:// port) instead of |
| "563". In this case Apache is not configured for mod_ssl; we just |
| happen to use port "443" in the way any random port would be used. |
| This could be handy if the Viewer side environment is restrictive in |
| that it only allows outgoing connections to ports 80 and 443 (and, |
| say, you didn't want to use port 80, or you wanted to use 80 for |
| something else). Another reason for using 443 would be some web proxy |
| environments only allow the CONNECT method to go to port 443 (and not |
| even the case 563 we use above). |
| |
| _________________________________________________________________ |
| |
| Details: |
| |
| Let's go through the httpd.conf additions in detail from the top. |
| |
| The LoadModules directives load the necessary apache modules. Note |
| that mod_rewrite must be listed first. If you are compiling from |
| scratch something like this worked for us: |
| ./configure --enable-proxy=shared --enable-proxy-connect=shared --enable-ssl= |
| shared --enable-rewrite=shared --prefix=/dist/apache |
| |
| Then the VirtualHost *:563 virtual host section starts. |
| |
| The "ProxyRequests On" and "AllowCONNECT 5915" enable the web server |
| to forward proxy requests to port 5915 (and only this port) INSIDE the |
| firewall. Think about the implications of this thoroughly and test it |
| carefully. |
| |
| The RewriteRule's are for convenience only so that the URL entered |
| into the Web browser does not need the various extra parameters, e.g.: |
| http://www.gateway.east:563/vnc/host2/index.vnc?CONNECT=host2+5915&PORT=563, |
| blah,blah... |
| |
| (or otherwise make direct edits to index.vnc to set these parameters). |
| The forceProxy=yes parameter is passed to the applet to force the use |
| of a outgoing proxy socket connection. Use it only if the Web browser |
| is inside a separate Web proxying environment (i.e. large corporation) |
| |
| The rewrites with parameter urlPrefix are described under Tricks for |
| Better Response. The "trust" ones (also described under Tricks) with |
| trustAllVncCerts tell the Java VNC applet to skip a dialog asking |
| about the VNC Certificate. They are a bit faster and more reliable |
| than the original method. In the best situation they lead to being |
| logged in 20 seconds or less (without them the time to login can be |
| much longer since a number of connections must timeout). |
| |
| All of the x11vnc Java Viewer applet parameters are described in the |
| file classes/ssl/README |
| |
| The external file /dist/apache/conf/vnc.hosts containing the allowed |
| VNC server hostnames is read in. Its 2nd column contains the VNC |
| display of the host (always 15 in our example; if you make it vary you |
| will need to adjust some lines in the httpd.conf accordingly, e.g. |
| AllowCONNECT). This list is used to constrain both the Jar file |
| download URL and the proxy CONNECT the VNC viewer makes to only the |
| intended VNC servers. |
| |
| Limiting the proxy CONNECT is done with the two sets of RewriteCond |
| conditions. |
| |
| Limiting the Jar file download URL is done in the remaining 4 |
| RewriteRule's. |
| |
| Note that these index.vnc and VncViewer.jar downloads to the browser |
| are not encrypted via SSL, and so in principle could be tampered with |
| by a really bad guy. The subsequent VNC connection, however, is |
| encrypted through a single SSL connection (it makes a CONNECT straight |
| to x11vnc). See below for how to have these initial downloads |
| encrypted as well (if the apache web server has SSL/mod_ssl, i.e. |
| https, enabled and configured). |
| |
| Unfortunately the Java VNC viewer applet currently is not able to save |
| its own list of Certificates (e.g. the user says trust this VNC |
| certificate 'always'). This is because an applet it cannot open local |
| files, etc. Sadly, the applet cannot even remember certificates in the |
| same browser session because it is completely reinitialized for each |
| connection (see below). |
| |
| _________________________________________________________________ |
| |
| Too Much? |
| |
| If these apache rules are a little too much for you, there is a little |
| bit simpler scheme where you have to list each of the individual |
| machines in the httpd.conf and ssl.conf files. It may be a little more |
| typing to maintain, but perhaps being more straight forward (less |
| RewriteRule's) is desirable. |
| |
| _________________________________________________________________ |
| |
| Problems? |
| |
| To see example x11vnc output for a successful https://host:5900/ |
| connection with the Java Applet see This Page. |
| |
| _________________________________________________________________ |
| |
| Some Ideas for adding extra authentication, etc. for the paranoid: |
| * VNC passwords: -rfbauth, -passwdfile, or -usepw. Even adding a |
| simple company-wide VNC password helps block unwanted access. |
| * Unix passwords: -unixpw |
| * SSL Client certificates: -sslverify |
| * Apache AuthUserFile directive: .htaccess, etc. |
| * Filter connections based on IP address or hostname. |
| * Use Port-knocking on your firewall as described in: Enhanced |
| TightVNC Viewer (ssvnc). |
| * Add proxy password authentication (requires Viewer changes?) |
| * Run a separate instance of Apache that provides this VNC service |
| so it can be brought up and down independently of the normal web |
| server. |
| * How secure is the Client side? Public machines in internet cafes, |
| etc, are often hacked, with backdoors and VNC servers of their |
| own. Prefer using your own firewalled laptop to a public machine. |
| |
| |
| _________________________________________________________________ |
| |
| Using non-Java viewers with this scheme: |
| |
| The ss_vncviewer stunnel wrapper script for VNC viewers has the -proxy |
| option that can take advantage of this method. |
| ss_vncviewer -proxy www.gateway.east:563 host1:15 |
| |
| For the case of the "double proxy" situation (see below) supply both |
| separated by a comma. |
| ss_vncviewer -proxy proxy1.foobar.com:8080,www.gateway.east:563 host1:15 |
| |
| For the Enhanced TightVNC Viewer (ssvnc) GUI (it uses ss_vncviewer on |
| Unix) put 'host1:15' into the 'VNC Server' entry box, and here are |
| possible Proxy/Gateway entries |
| Proxy/Gateway: www.gateway.east:563 |
| Proxy/Gateway: proxy1.foobar.com:8080,www.gateway.east:563 |
| |
| then click on the 'Connect' button. |
| |
| _________________________________________________________________ |
| |
| Downloading the Java applet to the browser via HTTPS: |
| |
| To have the Java applet downloaded to the user's Web Browser via an |
| encrypted (and evidently safer) SSL connection the Apache webserver |
| should be configured for SSL via mod_ssl. |
| |
| It is actually possible to use the x11vnc Key Management utility |
| "-sslGenCert" to generate your Apache/SSL .crt and .key files. (In |
| brief, run something like "x11vnc -sslGenCert server self:apache" then |
| copy the resulting self:apache.crt file to conf/ssl.crt/server.crt and |
| extract the private key part from self:apache.pem and paste it into |
| conf/ssl.key/server.key). Setting the env var REQ_ARGS='-days 1095' |
| before running x11vnc will bump up the expiration date (3 years in |
| this case). |
| |
| Or you can use the standard methods described in the Apache mod_ssl |
| documentation to create your keys. Then restart Apache, usually |
| something like "apachectl stop" followed by "apachectl startssl" |
| |
| In addition to the above sections in httpd.conf one should add the |
| following to ssl.conf: |
| SSLProxyEngine On |
| |
| RewriteEngine On |
| |
| # Convenience rules to expand applet parameters. These do not have a traili |
| ng "/" |
| # |
| # /vnc http jar file downloading: |
| # |
| RewriteRule /vnc/([^/]+)$ /vnc/$1/index.vnc?CONNECT=$ |
| 1+5915&PORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vnc_2F_$1 [R,NE,L] |
| RewriteRule /vnc/proxy/([^/]+)$ /vnc/$1/proxy.vnc?CONNECT=$ |
| 1+5915&PORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vnc_2F_$1&forceProxy=yes [R,N |
| E,L] |
| # |
| # (we skipped the "trust" ones above, put them in if you like) |
| # |
| # /vncs https jar file downloading: |
| # |
| RewriteRule /vncs/([^/]+)$ /vncs/$1/index.vnc?CONNECT=$ |
| 1+5915&PORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1 [R,NE,L] |
| RewriteRule /vncs/proxy/([^/]+)$ /vncs/$1/proxy.vnc?CONNECT=$ |
| 1+5915&PORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&forceProxy=yes [R, |
| NE,l] |
| RewriteRule /vncs/trust/([^/]+)$ /vncs/$1/index.vnc?CONNECT=$ |
| 1+5915&PORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&trustAllVncCerts=y |
| es [R,NE,L] |
| RewriteRule /vncs/trust/proxy/([^/]+)$ /vncs/$1/proxy.vnc?CONNECT=$ |
| 1+5915&PORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&forceProxy=yes&tru |
| stAllVncCerts=yes [R,NE,L] |
| |
| # Convenience rules used for the connect_switch helper (requires Listen 127. |
| 0.0.1:443 above): |
| # |
| RewriteRule /vnc443/([^/]+)$ /vncs/$1/index.vnc?CONNECT=$ |
| 1+5915&PORT=443&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1 [R,NE,L] |
| RewriteRule /vnc443/proxy/([^/]+)$ /vncs/$1/proxy.vnc?CONNECT=$ |
| 1+5915&PORT=443&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&forceProxy=yes [R, |
| NE,L] |
| RewriteRule /vnc443/trust/([^/]+)$ /vncs/$1/index.vnc?CONNECT=$ |
| 1+5915&PORT=443&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&trustAllVncCerts=y |
| es [R,NE,L] |
| RewriteRule /vnc443/trust/proxy/([^/]+)$ /vncs/$1/proxy.vnc?CONNECT=$ |
| 1+5915&PORT=443&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&forceProxy=yes&tru |
| stAllVncCerts=yes [R,NE,L] |
| |
| # Read in the allowed host to vnc display mapping file. It looks like: |
| # |
| # host1 15 |
| # host2 15 |
| # ... |
| # |
| # the display "15" means 5915 for SSL VNC and 5815 for http applet download. |
| # |
| RewriteMap vnchosts txt:/dist/apache/conf/vnc.hosts |
| |
| |
| # Remap /vnc and /vncs to the proxy http download (e.g. https://host:5915) |
| # |
| # First, fail if it starts with the string /vnc0: |
| # |
| RewriteRule ^/vnc0.* /VNCFAIL [F,L] |
| # |
| # Next, map the prefix to /vnc0:host:protocol:port |
| # |
| RewriteRule ^/vnc/([^/]+)/(.*) /vnc0/$1:http:58${vnchosts:$1|NOTFOUND}/$2 |
| [NE] |
| RewriteRule ^/vncs/([^/]+)/(.*) /vnc0/$1:https:59${vnchosts:$1|NOTFOUND}/$2 |
| [NE] |
| # |
| # Drop any not found: |
| # |
| RewriteRule ^/vnc0.*NOTFOUND.* /VNCFAIL [F,L] |
| |
| # Construct the proxy URL and retrieve it: |
| # |
| RewriteRule ^/vnc0/([^/]+):([^/]+):([^/]+)/(.*) $2://$1:$3/$4 [P,NE,L] |
| |
| This is all in the "<VirtualHost _default_:443>" section of ssl.conf. |
| |
| The user could then point the Web Browser to: |
| https://www.gateway.east/vnc/host2 |
| |
| or |
| https://www.gateway.east/vnc/proxy/host2 |
| |
| for the "double proxy" case. (Important: do not put a trailing "/" on |
| the URL, since that will defeat the RewriteRules.) |
| |
| As with the httpd.conf case, the external file |
| (/dist/apache/conf/vnc.hosts in the above example) contains the |
| hostnames of the allowed VNC servers. |
| |
| Note that inside the firewall the Java applet download traffic is not |
| encrypted (only over the Internet is SSL used) for these cases: |
| https://www.gateway.east/vnc/host2 |
| https://www.gateway.east/vnc/proxy/host2 |
| |
| However for the special "vncs" rules above: |
| https://www.gateway.east/vncs/host2 |
| |
| the Java applet download is encrypted via SSL for both legs. Note that |
| the two legs are two separate SSL sessions. So the data is decrypted |
| inside an apache process and reencrypted by the apache process for the |
| 2nd SSL session inside the same apache process (a very small gap one |
| might overlook). |
| |
| The "vncs/trust" ones are like the "trust" ones described earlier |
| https://www.gateway.east/vncs/trust/mach2 |
| |
| and similarly for the httpsPort ones. See Tricks for Better Response. |
| |
| In all of the above cases the VNC traffic from Viewer to x11vnc is |
| encrypted end-to-end in a single SSL session, even for the "double |
| proxy" case because the CONNECT method is used (there are actually two |
| CONNECT's for the "double proxy" case). This part (the VNC traffic) is |
| the most important part to have encrypted. |
| |
| Note that the Certificate dialogs the user has in his web browser will |
| be for the Apache Certificate, while for the Java applet it will be |
| the x11vnc certificate. |
| |
| Note also that you can have Apache serve up the Jar file VncViewer.jar |
| and/or index.vnc/proxy.vnc instead of each x11vnc if you want to. |
| |
| The rules in ssl.conf are similar to the ones in httpd.conf and so are |
| not discussed in detail. The only really new thing is the /vncs |
| handling to download the applet jar via HTTPS on port 5915. |
| |
| The special entries "/vnc443" are only used for the special helper |
| program (connect_switch) for the https port 443 only mode discussed |
| here. |
| |
| _________________________________________________________________ |
| |
| INETD automation: |
| |
| The "single-port" (i.e. 5915) HTTPS applet download and VNC connection |
| aspect shown here is convenient and also enables having x11vnc run out |
| of inetd. That way x11vnc is run on demand instead of being run all |
| the time (the user does not have to remember to start it). The first |
| connections to inetd download index.vnc and the Jar file (via https) |
| and the the last connection to inetd establishes the SSL VNC |
| connection. Since x11vnc is restarted for each connection, this will |
| be a bit slower than the normal process. |
| |
| For example, the /etc/inetd.conf line could be: |
| 5915 stream tcp nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc_ssl.sh |
| |
| where the script x11vnc_ssl.sh looks something like this: |
| #!/bin/sh |
| |
| /usr/local/bin/x11vnc -inetd -oa /var/log/x11vnc-15.log \ |
| -ssl SAVE -http -unixpw -localhost \ |
| -display :0 -auth /home/THE_USER/.Xauthority |
| |
| where, as usual, the inetd launching needs to know which user is |
| typically using the display on that machine. One could imagine giving |
| different users different ports, 5915, 5916, etc. to distinguish (then |
| the script would need to be passed the username). mod_rewrite could be |
| used to automatically map username in the URL to his port number. |
| |
| A better way is to use the "-display WAIT:cmd=FINDDISPLAY" feature to |
| autodetect the user and Xauthority data: |
| #!/bin/sh |
| |
| /usr/local/bin/x11vnc -inetd -oa /var/log/x11vnc-15.log \ |
| -ssl SAVE -http -unixpw -localhost -users unixpw= \ |
| -find |
| |
| (we have used the alias -find for "-display WAIT:cmd=FINDDISPLAY".) |
| This way the user must supply his Unix username and password and then |
| his display and Xauthority data on that machine will be located and |
| returned to x11vnc to allow it to attach. If he doesn't have a display |
| running on that machine or he fails to log in correctly, the |
| connection will be dropped. |
| |
| The variant "-display WAIT:cmd=FINDCREATEDISPLAY" (aliased by |
| "-create") will actually create a (virtual or real) X server session |
| for the user if one doesn't already exist. See here for details. |
| |
| To enable inetd operation for the non-HTTPS Java viewer download (port |
| 5815 in the above httpd.conf example) you will need to run x11vnc in |
| HTTPONCE mode on port 5815: For example, the /etc/inetd.conf line |
| could be: |
| 5815 stream tcp nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc \ |
| -inetd -prog /usr/local/bin/x11vnc -oa /var/log/x11vnc-15.log \ |
| -http_ssl -display WAIT:cmd=HTTPONCE |
| |
| where the long inetd.conf line has been split. Note how the -http_ssl |
| tries to automatically find the .../classes/ssl subdirectory. This |
| requires the -prog option available in x11vnc 0.8.4 (a shell script |
| wrapper, e.g. /usr/local/bin/x11vnc_http.sh can be used to work around |
| this). |
| |
| Also note the use of "-ssl SAVE" above. This way a saved server.pem is |
| used for each inetd invocation (rather generating a new one each time |
| as happens for "-ssl TMP"). Note that it cannot have a protecting |
| passphrase because inetd will not be able to supply it. |
| |
| Another option is: |
| 5815 stream tcp nowait root /usr/sbin/tcpd /usr/local/bin/x11vnc \ |
| -inetd -httpdir /usr/local/share/x11vnc/classes/ssl \ |
| -oa /var/log/x11vnc-15.log -display WAIT:cmd=HTTPONCE |
| |
| (this also requires a feature found in x11vnc 0.8.4). |
| _________________________________________________________________ |
| |
| Other Ideas: |
| |
| - The above schemes work, but they are a bit complicated with all of |
| the rigging. There should be more elegant ways to configure Apache to |
| do these, but we have not found them (please let us know if you |
| discover something nice). However, once this scheme has been set up |
| and is working it is easy to maintain and add/delete workstations, |
| etc. |
| |
| - In general Apache is not required, but it makes things convenient. |
| The firewall itself could do the port redirection via its firewall |
| rules. Evidently different Internet-facing ports would be required for |
| each workstation. This could be set up using iptables rules for |
| example. If there were just one or two machines this would be the |
| easiest method. For example: |
| iptables -t nat -A PREROUTING -p tcp -d 24.35.46.57 --dport 5901 -j DNAT --to |
| -destination 192.168.1.2:5915 |
| iptables -t nat -A PREROUTING -p tcp -d 24.35.46.57 --dport 5902 -j DNAT --to |
| -destination 192.168.1.3:5915 |
| |
| Where 24.35.46.57 is the internet IP address of the gateway. In this |
| example 24.35.46.57:5901 is redirected to the internal machine |
| 192.168.1.2:5915 and 24.35.46.57:5902 is redirected to another |
| internal machine 192.168.1.3:5915, both running x11vnc -ssl ... in SSL |
| mode. For this example, the user would point the web browser to, e.g.: |
| https://24.35.46.57:5901/?PORT=5901 |
| |
| or using the stunnel wrapper script: |
| ss_vncviewer 24.35.46.57:1 |
| |
| One can achieve similar things with dedicated firewall/routers (e.g. |
| Linksys) using the device's web or other interface to configure the |
| firewall. |
| |
| If the user may be coming out of a firewall using a proxy it may be |
| better to redirect ports 443 and 563 (instead of 5901 and 5902) to the |
| internal machines so that the user's proxy will allow CONNECTing to |
| them. |
| |
| - The redirection could also be done at the application level using a |
| TCP redirect program (e.g. ip_relay or fancier ones). Evidently more |
| careful internal hostname checking, etc., could be performed by the |
| special purpose application to add security. See connect_switch which |
| is somewhat related. |
| |
| - One might imagine the ProxyPass could be done for the VNC traffic as |
| well (for the ssl.conf case) to avoid the CONNECT proxying completely |
| (which would be nice to avoid). Unfortunately we were not able to get |
| this to work. Since HTTP is a request-response protocol (as opposed to |
| a full bidirectional link required by VNC that CONNECT provides) this |
| makes it difficult to do. It may be possible, but we haven't found out |
| how yet. |
| |
| All of the x11vnc Java Viewer applet parameters are described in the |
| file classes/ssl/README |
| |
| _________________________________________________________________ |
| |
| Tricks for Better Response and reliability: |
| |
| The "original scheme" using httpd.conf and ssl.conf rewrites without |
| urlPrefix and trustAllVncCerts above should work OK, but may lead to |
| slow and/or unreliable loading of the applet and final connection to |
| x11vnc. The following are what I do now to get better response and |
| reliability. YMMV. |
| |
| The problem with the "original scheme" is that there is a point where |
| the VNC Viewer applet can try up to 3 times to retrieve the x11vnc |
| certificate, since it needs to get it to show it to you and ask you if |
| you accept it. This can add about 45 seconds to the whole process |
| (which takes 1 to 1.5 minutes with all the dialogs) since a couple of |
| those connections must time out. The "trust" items in the config add a |
| parameter trustAllVncCerts=yes similar to the forceProxy=yes |
| parameter. This can cut the total time to the VNC password prompt down |
| to 15 seconds which is pretty good. (Note by ignoring the certificate |
| this does not protect against man-in-the-middle attacks which are |
| rare, but maybe the won't be so rare in the future... see |
| dsniff/webmitm and cain) |
| |
| First make sure the x11vnc SSL certificate+key is the same as |
| Apache's. (otherwise you may get one extra dialog and/or one extra |
| connection that has to time out). |
| |
| The following RewriteRule's are the same now advocated in the |
| instructions above. |
| |
| The httpsPort and urlPrefix= parameters give hints to the applet to |
| improve connecting: This is what goes in httpd.conf: |
| RewriteEngine On |
| RewriteRule /vnc/([^/]+)$ /vnc/$1/index.vnc?CONNECT=$1+5915&PO |
| RT=563&urlPrefix=_2F_vnc_2F_$1 [R,NE] |
| RewriteRule /vnc/trust/([^/]+)$ /vnc/$1/index.vnc?CONNECT=$1+5915&PO |
| RT=563&urlPrefix=_2F_vnc_2F_$1&trustAllVncCerts=yes [R,NE] |
| RewriteRule /vnc/proxy/([^/]+)$ /vnc/$1/proxy.vnc?CONNECT=$1+5915&PO |
| RT=563&urlPrefix=_2F_vnc_2F_$1&forceProxy=yes [R,NE] |
| RewriteRule /vnc/trust/proxy/([^/]+)$ /vnc/$1/proxy.vnc?CONNECT=$1+5915&PO |
| RT=563&urlPrefix=_2F_vnc_2F_$1&forceProxy=yes&trustAllVncCerts=yes [R,NE] |
| |
| The httpsPort and urlPrefix provide useful hints to the VNC Viewer |
| applet when it connects to x11vnc to glean information about Proxies, |
| certificates, etc. |
| |
| This is what goes into ssl.conf: |
| RewriteEngine On |
| RewriteRule /vnc/([^/]+)$ /vnc/$1/index.vnc?CONNECT=$1+5915&P |
| ORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vnc_2F_$1 [R,NE] |
| RewriteRule /vnc/proxy/([^/]+)$ /vnc/$1/proxy.vnc?CONNECT=$1+5915&P |
| ORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vnc_2F_$1&forceProxy=yes [R,NE] |
| RewriteRule /vncs/([^/]+)$ /vncs/$1/index.vnc?CONNECT=$1+5915&P |
| ORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1 [R,NE] |
| RewriteRule /vncs/proxy/([^/]+)$ /vncs/$1/proxy.vnc?CONNECT=$1+5915&P |
| ORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&forceProxy=yes [R,NE] |
| RewriteRule /vncs/trust/([^/]+)$ /vncs/$1/index.vnc?CONNECT=$1+5915&P |
| ORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&trustAllVncCerts=yes [R,NE |
| ] |
| RewriteRule /vncs/trust/proxy/([^/]+)$ /vncs/$1/proxy.vnc?CONNECT=$1+5915&P |
| ORT=563&httpsPort=443&GET=1&urlPrefix=_2F_vncs_2F_$1&forceProxy=yes&trustAllVnc |
| Certs=yes [R,NE] |
| |
| The rest is the same. |
| |
| The httpsPort and urlPrefix and GET provide useful hints to the VNC |
| Viewer applet when it connects to x11vnc to glean information about |
| Proxies, certificates, etc, and also for the ultimate VNC connection |
| (GET speeds this up by sending a special HTTP GET to cause x11vnc to |
| immediately switch to the VNC protocol). |
| |
| To turn these into URLs, as was done above, take the string in the |
| RewriteRule, e.g. /vncs and turn it into |
| https://gateway/vncs/machinename Similarly for non-https: |
| http://gateway:563/vnc/machinename |
| |
| If you use the 'trust' ones, you are performing NO checks, visual or |
| otherwise, on the VNC SSL certificate. It is trusted without question. |
| This speeds things up because it avoids a dialog about certificates, |
| but of course has some risk WRT Man in the Middle attacks. I don't |
| recommend them. It is better to use /vnc or /vncs and the first time |
| you connect carefully check the Certificate and then tell your Browser |
| and Java Virtual Machine to trust the certificate 'Always'. Then if |
| you later get an unexpected dialog, you know something is wrong. |
| Nearly always it is just a changed or expired certificate, but better |
| safe than sorry... |
| |
| ======================================================================= |
| http://www.karlrunge.com/x11vnc/enhanced_tightvnc_viewer.html: |
| |
| |
| _________________________________________________________________ |
| |
| Enhanced TightVNC Viewer (SSVNC: SSL/SSH VNC viewer) |
| |
| (To Downloads) (To Quick Start) |
| |
| [ssvnc.gif] [ssvnc_windows.gif] [ssvnc_macosx.gif] . . |
| |
| |
| The Enhanced TightVNC Viewer, SSVNC, adds encryption security to VNC |
| connections. |
| |
| The package provides a GUI for Windows, Mac OS X, and Unix that |
| automatically starts up an STUNNEL SSL tunnel for SSL or ssh/plink for |
| SSH connections to any VNC server, such as x11vnc, and then launches |
| the VNC Viewer to use the encrypted tunnel. |
| |
| The x11vnc server has built-in SSL support, however SSVNC can make SSL |
| encrypted VNC connections to any VNC Server if they are running an SSL |
| tunnel, such as STUNNEL or socat, at their end. SSVNC's SSH tunnel |
| will work to any VNC Server host running sshd that you can log into. |
| |
| The Enhanced TightVNC Viewer package started as a project to add some |
| patches to the long neglected Unix TightVNC Viewer. However, now the |
| front-end GUI, encryption, and wrapper scripts features possibly |
| outweigh the Unix TightVNC Viewer improvements (see the lists below to |
| compare). |
| |
| The SSVNC Unix vncviewer can also be run without the SSVNC encryption |
| GUI as an enhanced replacement for the xvncviewer, xtightvncviewer, |
| etc., viewers. |
| |
| In addition to normal SSL, SSVNC also supports the VeNCrypt SSL/TLS |
| and Vino/ANONTLS encryption extensions to VNC on Unix, Mac OS X, and |
| Windows. Via the provided SSVNC VeNCrypt bridge, VeNCrypt and ANONTLS |
| encryption also works with any third party VNC Viewer (e.g. RealVNC, |
| TightVNC, UltraVNC, etc...) you select via 'Change VNC Viewer'. |
| |
| The short name for this project is "ssvnc" for SSL/SSH VNC Viewer. |
| This is the name of the command to start it. |
| |
| There is a simplified SSH-Only mode (sshvnc). And an even more |
| simplified Terminal-Services mode (tsvnc) for use with x11vnc on the |
| remote side. |
| |
| The tool has many additional features; see the descriptions below. |
| |
| It is a self-contained bundle, you could carry it around on, say, a |
| USB memory stick / flash drive for secure VNC viewing from almost any |
| machine, Unix, Mac OS X, and Windows (and if you create a directory |
| named "Home" in the toplevel ssvnc directory on the drive your VNC |
| profiles and certs will be kept there as well). For Unix, there is |
| also a conventional source tarball to build and install in the normal |
| way and not use a pre-built bundle. |
| |
| _________________________________________________________________ |
| |
| Announcements: |
| |
| Important: If you created any SSL certificates with SSVNC (or anything |
| else) on a Debian or Ubuntu system from Sept. 2006 through May 2008, |
| then those keys are likely extremely weak and can be easily cracked. |
| The certificate files should be deleted and recreated on a non-Debian |
| system or an updated one. See |
| http://www.debian.org/security/2008/dsa-1571 for details. The same |
| applies to SSH keys. |
| |
| Please read this information on using SSVNC on workstations with |
| Untrusted Local Users. |
| |
| _________________________________________________________________ |
| |
| Feature List: |
| |
| Wrapper scripts and a tcl/tk GUI were written to create these features |
| for Unix, Mac OS X, and Windows: |
| * SSL support for connections using the bundled stunnel program. |
| * Automatic SSH connections from the GUI (system ssh is used on Unix |
| and MacOS X; bundled plink is used on Windows) |
| * Ability to Save and Load VNC profiles for different hosts. |
| * You can also use your own VNC Viewer, e.g. UltraVNC or RealVNC, |
| with the SSVNC encryption GUI front-end if you prefer. |
| * Create or Import SSL Certificates and Private Keys. |
| * Reverse (viewer listening) VNC connections via SSL and SSH. |
| * VeNCrypt SSL/TLS VNC encryption support (used by VeNCrypt, QEMU, |
| ggi, libvirt/virt-manager/xen, vinagre/gvncviewer/gtk-vnc) |
| * ANONTLS SSL/TLS VNC encryption support (used by Vino) |
| * VeNCrypt and ANONTLS are also enabled for any 3rd party VNC Viewer |
| (e.g. RealVNC, TightVNC, UltraVNC ...) on Unix, MacOSX, and |
| Windows via the provided SSVNC VeNCrypt Viewer Bridge tool (use |
| 'Change VNC Viewer' to select the one you want.) |
| * Support for Web Proxies, SOCKS Proxies, and the UltraVNC repeater |
| proxy (e.g. repeater://host:port+ID:1234). Multiple proxies may be |
| chained together (3 max). |
| * Support for SSH Gateway connections and non-standard SSH ports. |
| * Automatic Service tunnelling via SSH for CUPS and SMB Printing, |
| ESD/ARTSD Audio, and SMB (Windows/Samba) filesystem mounting. |
| * Sets up any additional SSH port redirections that you want. |
| * Zeroconf (aka Bonjour) is used on Unix and Mac OS X to find VNC |
| servers on your local network if the avahi-browse or dns-sd |
| program is available and in your PATH. |
| * Port Knocking for "closed port" SSH/SSL connections. In addition |
| to a simple fixed port sequence and one-time-pad implementation, a |
| hook is also provided to run any port knocking client before |
| connecting. |
| * Support for native MacOS X usage with bundled Chicken of the VNC |
| viewer (the Unix X11 viewer is also provided for MacOS X, and is |
| better IMHO. It is now the default on MacOS X.) |
| * Dynamic VNC Server Port determination and redirection (using ssh's |
| builtin SOCKS proxy, ssh -D) for servers like x11vnc that print |
| out PORT= at startup. |
| * Unix Username and Password entry for use with "x11vnc -unixpw" |
| type login dialogs. |
| * Simplified mode launched by command "sshvnc" that is SSH Only. |
| * Simplified mode launched by command "tsvnc" that provides a VNC |
| "Terminal Services" mode (uses x11vnc on the remote side). |
| * IPv6 support for all connection modes on Unix, MacOSX, and |
| Windows. |
| |
| Patches to TightVNC 1.3.9 vnc_unixsrc tree were created for Unix |
| TightVNC Viewer improvements (these only apply to the Unix VNC viewer, |
| including MacOSX XQuartz): |
| * rfbNewFBSize VNC support (dynamic screen resizing) |
| * Client-side Scaling of the Desktop in the viewer. |
| * ZRLE VNC encoding support (RealVNC's encoding) |
| * Support for the ZYWRLE encoding, a wavelet based extension to ZRLE |
| to improve compression of motion video and photo regions. |
| * TurboVNC support (VirtualGL's modified TightVNC encoding; requires |
| TurboJPEG library) |
| * Pipelined Updates of the framebuffer as in TurboVNC (asks for the |
| next update before the current one has finished downloading; this |
| gives some speedup on high latency connections.) |
| * Cursor alphablending with x11vnc at 32bpp (-alpha option) |
| * Option "-unixpw ..." for use with "x11vnc -unixpw" type login |
| dialogs. |
| * Support for UltraVNC extensions: 1/n Server side scaling, Text |
| Chat, Single Window, Disable Server-side Input. Both UltraVNC and |
| x11vnc servers support these extensions. |
| * UltraVNC File Transfer via an auxiliary Java helper program (java |
| must be in $PATH). Note that the x11vnc server also supports |
| UltraVNC file transfer. |
| * Connection support for the UltraVNC repeater proxy (-repeater |
| option). |
| * Support for UltraVNC Single Click operation. (both unencrypted: SC |
| I, and SSL encrypted: SC III) |
| * Support for UltraVNC DSM Encryption Plugin symmetric encryption |
| mode. (ARC4, AESV2, MSRC4, and SecureVNC) |
| * Support for UltraVNC MS-Logon authentication (NOTE: the UltraVNC |
| MS-Logon key exchange implementation is very weak; an eavesdropper |
| on the network can recover your Windows password easily in a few |
| seconds; you need to use an additional encrypted tunnel with |
| MS-Logon.) |
| * Support for symmetric encryption (including blowfish and 3des |
| ciphers) to Non-UltraVNC Servers. Any server using the same |
| encryption method will work, e.g.: x11vnc -enc blowfish:./my.key |
| * Instead of hostname:display one can also supply "exec=command |
| args..." to connect the viewer to the stdio of an external command |
| (e.g. stunnel or socat) rather than using a TCP/IP socket. Unix |
| domain sockets, e.g. /path/to/unix/socket, and a previously opened |
| file descriptor fd=0, work too. |
| * Local Port Protections for STUNNEL and SSH: avoid having for long |
| periods of time a listening port on the the local (VNC viewer) |
| side that redirects to the remote side. |
| * Reverse (viewer listening) VNC connections can show a Popup dialog |
| asking whether to accept the connection or not (-acceptpopup.) The |
| extra info provided by UltraVNC Single Click reverse connections |
| is also supported (-acceptpopupsc) |
| * Extremely low color modes: 64 and 8 colors in 8bpp |
| (-use64/-bgr222, -use8/-bgr111) |
| * Medium color mode: 16bpp mode on a 32bpp Viewer display |
| (-16bpp/-bgr565) |
| * For use with x11vnc's client-side caching -ncache method use the |
| cropping option -ycrop n. This will "hide" the large pixel buffer |
| cache below the actual display. Set to the actual height or use -1 |
| for autodetection (also, tall screens, H > 2*W, are autodetected |
| by default). |
| * Escape Keys: specify a set of modifier keys so that when they are |
| all pressed down you can invoke Popup menu actions via keystrokes. |
| I.e., a set of 'Hot Keys'. One can also pan (move) the desktop |
| inside the viewport via Arrow keys or a mouse drag. |
| * Scrollbar width setting: -sbwidth n, the default is very thin, 2 |
| pixels, for less distracting -ycrop usage. |
| * Selection text sending and receiving can be fine-tuned with the |
| -sendclipboard, -sendalways, and -recvtext options. |
| * TightVNC compression and quality levels are automatically set |
| based on observed network latency (n.b. not bandwidth.) |
| * Improvements to the Popup menu, all of these can now be changed |
| dynamically via the menu: ViewOnly, Toggle Bell, CursorShape |
| updates, X11 Cursor, Cursor Alphablending, Toggle Tight/ZRLE, |
| Toggle JPEG, FullColor/16bpp/8bpp (256/64/8 colors), Greyscale for |
| low color modes, Scaling the Viewer resolution, Escape Keys, |
| Pipeline Updates, and others, including UltraVNC extensions. |
| * Maintains its own BackingStore if the X server does not. |
| * The default for localhost:0 connections is not raw encoding since |
| same-machine connections are pretty rare. Default assumes you are |
| using a SSL or SSH tunnel. Use -rawlocal to revert. |
| * XGrabServer support for fullscreen mode, for old window managers |
| (-grab/-graball option). |
| * Fix for Popup menu positioning for old window managers (-popupfix |
| option). |
| * The VNC Viewer ssvncviewer supports IPv6 natively (no helpers |
| needed.) |
| |
| The list of 3rd party software bundled in the archive files: |
| * TightVNC Viewer (windows, unix, macosx) |
| * Chicken of the VNC Viewer (macosx) |
| * Stunnel (windows, unix, macosx) |
| * Putty/Plink/Pageant (windows) |
| * OpenSSL (windows) |
| * esound (windows) |
| |
| These are all self-contained in the bundle directory: they will not be |
| installed on your system. Just un-zip or un-tar the file you |
| downloaded and run the frontend ssvnc straight from its directory. |
| Alternatively, on Unix you can use the conventional source tarball. |
| |
| _________________________________________________________________ |
| |
| Here is the Quick Start info from the README for how to setup and use |
| SSVNC: |
| Quick Start: |
| ----------- |
| |
| Unix and Mac OS X: |
| |
| Inside a Terminal do something like the following. |
| |
| Unpack the archive: |
| |
| % gzip -dc ssvnc-1.0.29.tar.gz | tar xvf - |
| |
| Run the GUI: |
| |
| % ./ssvnc/Unix/ssvnc (for Unix) |
| |
| % ./ssvnc/MacOSX/ssvnc (for Mac OS X) |
| |
| The smaller file "ssvnc_no_windows-1.0.29.tar.gz" |
| could have been used as well. |
| |
| On MacOSX you could also click on the SSVNC app icon in the Finder. |
| |
| On MacOSX if you don't like the Chicken of the VNC (e.g. no local |
| cursors, no screen size rescaling, and no password prompting), and you |
| have the XDarwin X server installed, you can set DISPLAY before starting |
| ssvnc (or type DISPLAY=... in Host:Disp and hit Return). Then our |
| enhanced TightVNC viewer will be used instead of COTVNC. |
| Update: there is now a 'Use X11 vncviewer on MacOSX' under Options ... |
| |
| |
| If you want a SSH-only tool (without the distractions of SSL) run |
| the command: |
| |
| sshvnc |
| |
| instead of "ssvnc". Or click "SSH-Only Mode" under Options. |
| Control-h will toggle between the two modes. |
| |
| |
| If you want a simple VNC Terminal Services only mode (requires x11vnc |
| on the remote server) run the command: |
| |
| tsvnc |
| |
| instead of "ssvnc". Or click "Terminal Services" under Options. |
| Control-t will toggle between the two modes. |
| |
| "tsvnc profile-name" and "tsvnc user@hostname" work too. |
| |
| |
| Unix/MacOSX Install: |
| |
| There is no standard install for the bundles, but you can make |
| symlinks like so: |
| |
| cd /a/directory/in/PATH |
| ln -s /path/to/ssvnc/bin/{s,t}* . |
| |
| Or put /path/to/ssvnc/bin, /path/to/ssvnc/Unix, or /path/to/ssvnc/MacOSX |
| in your PATH. |
| |
| For the conventional source tarball it will compile and install, e.g.: |
| |
| gzip -dc ssvnc-1.0.29.src.tar.gz | tar xvf - |
| cd ssvnc-1.0.29 |
| make config |
| make all |
| make PREFIX=/my/install/dir install |
| |
| then have /my/install/dir/bin in your PATH. |
| |
| |
| |
| Windows: |
| |
| Unzip, using WinZip or a similar utility, the zip file: |
| |
| ssvnc-1.0.29.zip |
| |
| Run the GUI, e.g.: |
| |
| Start -> Run -> Browse |
| |
| and then navigate to |
| |
| .../ssvnc/Windows/ssvnc.exe |
| |
| select Open, and then OK to launch it. |
| |
| The smaller file "ssvnc_windows_only-1.0.29.zip" |
| could have been used as well. |
| |
| You can make a Windows shortcut to this program if you want to. |
| |
| See the Windows/README.txt for more info. |
| |
| |
| If you want a SSH-only tool (without the distractions of SSL) run |
| the command: |
| |
| sshvnc.bat |
| |
| Or click "SSH-Only Mode" under Options. |
| |
| |
| If you want a simple VNC Terminal Services only mode (requires x11vnc |
| on the remote server) run the command: |
| |
| tsvnc.bat |
| |
| Or click "Terminal Services" under Options. Control-t will toggle |
| between the two modes. "tsvnc profile-name" and "tsvnc user@hostname" |
| work too. |
| |
| _________________________________________________________________ |
| |
| You can read all of the SSVNC GUI's Online Help Text here. |
| _________________________________________________________________ |
| |
| The bundle unpacks a directory/folder named: ssvnc. It contains these |
| programs to launch the GUI: |
| Windows/ssvnc.exe for Windows |
| MacOSX/ssvnc for Mac OS X |
| Unix/ssvnc for Unix |
| |
| (the Mac OS X and Unix launchers are simply links to the bin |
| directory). See the README for more information. |
| |
| The SSH-Only mode launcher program has name sshvnc. The Terminal |
| Services mode launcher program (assumes x11vnc 0.8.4 or later and Xvfb |
| installed on the server machine) has name tsvnc. |
| |
| The Viewer SSL support is done via a wrapper script (bin/ssvnc_cmd |
| that calls bin/util/ss_vncviewer) that starts up the STUNNEL tunnel |
| first and then starts the TightVNC viewer pointed at that tunnel. The |
| bin/ssvnc program is a GUI front-end to that script. See this FAQ for |
| more details on SSL tunnelling. In SSH connection mode, the wrappers |
| start up SSH appropriately. |
| |
| |
| Memory Stick Usage: If you create a directory named "Home" in that |
| toplevel ssvnc directory then that will be used as the base for |
| storing VNC profiles and certificates. Also, for convenience, if you |
| first run the command with "." as an argument (e.g. "ssvnc .") it will |
| automatically create the "Home" directory for you. This is handy if |
| you want to place SSVNC on a USB flash drive that you carry around for |
| mobile use and you want the profiles you create to stay with the drive |
| (otherwise you'd have to browse to the drive directory each time you |
| load or save). |
| |
| One user on Windows created a BAT file to launch SSVNC and needed to |
| do this to get the Home directory correct: |
| cd \ssvnc\Windows |
| start \ssvnc\Windows\ssvnc.exe |
| |
| (an optional profile name can be supplied to the ssvnc.exe line) |
| |
| WARNING: if you use ssvnc from an "Internet Cafe", i.e. some untrusted |
| computer, please be aware that someone may have set up that machine to |
| be capturing your keystrokes, etc. |
| |
| |
| SSH-Only version: The command "sshvnc" can be run instead of "ssvnc" |
| to get an SSH-only version of the tool: |
| |
| [sshvnc.gif] |
| |
| These also work: "sshvnc myprofile" and "sshvnc user@hostname". To |
| switch from the regular SSVNC mode, click "SSH-Only Mode" under |
| Options. This mode is less distracting if you never plan to use SSL, |
| manage certificates, etc. |
| |
| |
| Terminal Services Only: The command "tsvnc" can be run instead of |
| "ssvnc" to get a "Terminal Services" only version of the tool: |
| |
| [tsvnc.gif] |
| |
| These also work: "tsvnc myprofile" and "tsvnc user@hostname". To |
| switch from the regular SSVNC mode, click "Terminal Services" under |
| Options. |
| |
| This mode requires x11vnc (0.9.3 or later) installed on the remote |
| machine to find, create, and manage the user sessions. SSH is used to |
| create the encrypted and authenticated tunnel. The Xvfb (virtual |
| framebuffer X server) program must also be installed on the remote |
| system. However tsvnc will also connect to a real X session (i.e. on |
| the physical hardware) if you are already logged into the X session; |
| this is a useful access mode and does not require Xvfb on the remote |
| system. |
| |
| This mode should be very easy for beginner users to understand and |
| use. On the remote end you only need to have x11vnc and Xvfb available |
| in $PATH, and on the local end you just run something like: |
| tsvnc myname@myhost.com |
| |
| (or start up the tsvnc GUI first and then enter myname@myhost.com and |
| press "Connect"). |
| |
| Normally the Terminal Services sessions created are virtual (RAM-only) |
| ones (e.g. Xvfb, Xdummy, or Xvnc), however a nice feature is if you |
| have a regular X session (i.e displaying on the physical hardware) on |
| the remote machine that you are ALREADY logged into, then the x11vnc |
| run from tsvnc will find it for you as well. |
| |
| Also, there is setting "X Login" under Advanced Options that allows |
| you to attach to a real X server with no one logged in yet (i.e. |
| XDM/GDM/KDM Login Greeter screen) as long as you have sudo(1) |
| permission on the remote machine. |
| |
| Nice features to soon to be added to the tsvnc mode are easy CUPS |
| printing (working fairly well) and Sound redirection (needs much work) |
| of the Terminal Services Desktop session. It is easier in tsvnc mode |
| because the entire desktop session can be started with the correct |
| environment. ssvnc tries to handle the general case of an already |
| started desktop and that is more difficult. |
| |
| |
| Proxies: Web proxies, SOCKS proxies, and the UltraVNC repeater proxy |
| are supported to allow the SSVNC connection to go through the proxy to |
| the otherwise unreachable VNC Server. SSH gateway machines can be used |
| in the same way. Read more about SSVNC proxy support here. |
| |
| |
| Dynamic VNC Server Port determination: If you are running SSVNC on |
| Unix and are using SSH to start the remote VNC server and the VNC |
| server prints out the line "PORT=NNNN" to indicate which dynamic port |
| it is using (x11vnc does this), then if you prefix the SSH command |
| with "PORT=" SSVNC will watch for the PORT=NNNN line and uses ssh's |
| built in SOCKS proxy (ssh -D ...) to connect to the dynamic VNC server |
| port through the SSH tunnel. For example: |
| VNC Host:Display user@somehost.com |
| Remote SSH Command: PORT= x11vnc -find |
| |
| or "PORT= x11vnc -display :0 -localhost", etc. Or use "P= x11vnc ..." |
| |
| There is also code to detect the display of the regular Unix |
| vncserver(1). It extracts the display (and hence port) from the lines |
| "New 'X' desktop is hostname:4" and also "VNC server is already |
| running as :4". So you can use something like: |
| PORT= vncserver; sleep 15 |
| or: PORT= vncserver :4; sleep 15 |
| |
| the latter is preferred because when you reconnect with it will find |
| the already running one. The former one will keep creating new X |
| sessions if called repeatedly. |
| |
| If you use PORT= on Windows, a large random port is selected instead |
| and the -rfbport option is passed to x11vnc (it does not work with |
| vncserver). |
| |
| |
| |
| Patches for Unix Tightvnc viewer: |
| |
| The rfbNewFBSize support allows the enhanced TightVNC Unix viewer to |
| resize when the server does (e.g. "x11vnc -R scale=3/4" remote control |
| command). |
| |
| The cursor alphablending is described here. |
| |
| The RealVNC ZRLE encoding is supported, in addition to some low colors |
| modes (16bpp and 8bpp at 256, 64, and even 8 colors, for use on very |
| slow connections). Greyscales are also enabled for the low color |
| modes. |
| |
| The Popup menu (F8) is enhanced with the ability to change many things |
| on the fly. F9 is added as a shortcut to toggle FullScreen mode. |
| |
| Client Side Caching: The x11vnc client-side caching is handled nicely |
| by this viewer. The very large pixel cache below the actual display in |
| this caching method is distracting. Our Unix VNC viewer will |
| automatically try to autodetect the actual display height if the |
| framebuffer is very tall (more than twice as high as it is wide). One |
| can also set the height to the known value via -ycrop n, or use -ycrop |
| -1 to force autodection. In fullscreen mode one is not possible to |
| scroll down to the pixel cache region. In non-fullscreen mode the |
| window manager frame is "shrink-wrapped" around the actual screen |
| display. You can still scroll down to the pixel cache region. The |
| scrollbars are set to be very thin (2 pixels) to be less distracting. |
| Use the -sbwidth n to make them wider. |
| |
| Probably nobody is interested in the grabserver patch for old window |
| managers when the viewer is in fullscreen mode... This and some other |
| unfixed bugs have been fixed in our patches (fullscreen toggle works |
| with KDE, -x11cursor has been fixed, and the dot cursor has been made |
| smaller). |
| |
| From the -help output: |
| SSVNC Viewer (based on TightVNC viewer version 1.3.9) |
| |
| Usage: vncviewer [<OPTIONS>] [<HOST>][:<DISPLAY#>] |
| vncviewer [<OPTIONS>] [<HOST>][::<PORT#>] |
| vncviewer [<OPTIONS>] exec=[CMD ARGS...] |
| vncviewer [<OPTIONS>] fd=n |
| vncviewer [<OPTIONS>] /path/to/unix/socket |
| vncviewer [<OPTIONS>] -listen [<DISPLAY#>] |
| vncviewer -help |
| |
| <OPTIONS> are standard Xt options, or: |
| -via <GATEWAY> |
| -shared (set by default) |
| -noshared |
| -viewonly |
| -fullscreen |
| -noraiseonbeep |
| -passwd <PASSWD-FILENAME> (standard VNC authentication) |
| -user <USERNAME> (Unix login authentication) |
| -encodings <ENCODING-LIST> (e.g. "tight,copyrect") |
| -bgr233 |
| -owncmap |
| -truecolour |
| -depth <DEPTH> |
| -compresslevel <COMPRESS-VALUE> (0..9: 0-fast, 9-best) |
| -quality <JPEG-QUALITY-VALUE> (0..9: 0-low, 9-high) |
| -nojpeg |
| -nocursorshape |
| -x11cursor |
| -autopass |
| |
| Option names may be abbreviated, e.g. -bgr instead of -bgr233. |
| See the manual page for more information. |
| |
| |
| Enhanced TightVNC viewer (SSVNC) options: |
| |
| URL http://www.karlrunge.com/x11vnc/ssvnc.html |
| |
| Note: ZRLE and ZYWRLE encodings are now supported. |
| |
| Note: F9 is shortcut to Toggle FullScreen mode. |
| |
| Note: In -listen mode set the env var. SSVNC_MULTIPLE_LISTEN=1 |
| to allow more than one incoming VNC server at a time. |
| This is the same as -multilisten described below. Set |
| SSVNC_MULTIPLE_LISTEN=MAX:n to allow no more than "n" |
| simultaneous reverse connections. |
| |
| Note: If the host:port is specified as "exec=command args..." |
| then instead of making a TCP/IP socket connection to the |
| remote VNC server, "command args..." is executed and the |
| viewer is attached to its stdio. This enables tunnelling |
| established via an external command, e.g. an stunnel(8) |
| that does not involve a listening socket. This mode does |
| not work for -listen reverse connections. |
| |
| If the host:port is specified as "fd=n" then it is assumed |
| n is an already opened file descriptor to the socket. (i.e |
| the parent did fork+exec) |
| |
| If the host:port contains a '/' it is interpreted as a |
| unix-domain socket (AF_LOCAL insead of AF_INET) |
| |
| -multilisten As in -listen (reverse connection listening) except |
| allow more than one incoming VNC server to be connected |
| at a time. The default for -listen of only one at a |
| time tries to play it safe by not allowing anyone on |
| the network to put (many) desktops on your screen over |
| a long window of time. Use -multilisten for no limit. |
| |
| -acceptpopup In -listen (reverse connection listening) mode when |
| a reverse VNC connection comes in show a popup asking |
| whether to Accept or Reject the connection. The IP |
| address of the connecting host is shown. Same as |
| setting the env. var. SSVNC_ACCEPT_POPUP=1. |
| |
| -acceptpopupsc As in -acceptpopup except assume UltraVNC Single |
| Click (SC) server. Retrieve User and ComputerName |
| info from UltraVNC Server and display in the Popup. |
| |
| -use64 In -bgr233 mode, use 64 colors instead of 256. |
| -bgr222 Same as -use64. |
| |
| -use8 In -bgr233 mode, use 8 colors instead of 256. |
| -bgr111 Same as -use8. |
| |
| -16bpp If the vnc viewer X display is depth 24 at 32bpp |
| request a 16bpp format from the VNC server to cut |
| network traffic by up to 2X, then tranlate the |
| pixels to 32bpp locally. |
| -bgr565 Same as -16bpp. |
| |
| -grey Use a grey scale for the 16- and 8-bpp modes. |
| |
| -alpha Use alphablending transparency for local cursors |
| requires: x11vnc server, both client and server |
| must be 32bpp and same endianness. |
| |
| -scale str Scale the desktop locally. The string "str" can |
| a floating point ratio, e.g. "0.9", or a fraction, |
| e.g. "3/4", or WxH, e.g. 1280x1024. Use "fit" |
| to fit in the current screen size. Use "auto" to |
| fit in the window size. "str" can also be set by |
| the env. var. SSVNC_SCALE. |
| |
| If you observe mouse trail painting errors, enable |
| X11 Cursor mode (either via Popup or -x11cursor.) |
| |
| Note that scaling is done in software and so can be |
| slow and requires more memory. Some speedup Tips: |
| |
| ZRLE is faster than Tight in this mode. When |
| scaling is first detected, the encoding will |
| be automatically switched to ZRLE. Use the |
| Popup menu if you want to go back to Tight. |
| Set SSVNC_PRESERVE_ENCODING=1 to disable this. |
| |
| Use a solid background on the remote side. |
| (e.g. manually or via x11vnc -solid ...) |
| |
| If the remote server is x11vnc, try client |
| side caching: x11vnc -ncache 10 ... |
| |
| -ycrop n Only show the top n rows of the framebuffer. For |
| use with x11vnc -ncache client caching option |
| to help "hide" the pixel cache region. |
| Use a negative value (e.g. -1) for autodetection. |
| Autodetection will always take place if the remote |
| fb height is more than 2 times the width. |
| |
| -sbwidth n Scrollbar width for x11vnc -ncache mode (-ycrop), |
| default is very narrow: 2 pixels, it is narrow to |
| avoid distraction in -ycrop mode. |
| |
| -nobell Disable bell. |
| |
| -rawlocal Prefer raw encoding for localhost, default is |
| no, i.e. assumes you have a SSH tunnel instead. |
| |
| -notty Try to avoid using the terminal for interactive |
| responses: use windows for messages and prompting |
| instead. Messages will also be printed to terminal. |
| |
| -sendclipboard Send the X CLIPBOARD selection (i.e. Ctrl+C, |
| Ctrl+V) instead of the X PRIMARY selection (mouse |
| select and middle button paste.) |
| |
| -sendalways Whenever the mouse enters the VNC viewer main |
| window, send the selection to the VNC server even if |
| it has not changed. This is like the Xt resource |
| translation SelectionToVNC(always) |
| |
| -recvtext str When cut text is received from the VNC server, |
| ssvncviewer will set both the X PRIMARY and the |
| X CLIPBOARD local selections. To control which |
| is set, specify 'str' as 'primary', 'clipboard', |
| or 'both' (the default.) |
| |
| -graball Grab the entire X server when in fullscreen mode, |
| needed by some old window managers like fvwm2. |
| |
| -popupfix Warp the popup back to the pointer position, |
| needed by some old window managers like fvwm2. |
| -sendclipboard Send the X CLIPBOARD selection (i.e. Ctrl+C, |
| Ctrl+V) instead of the X PRIMARY selection (mouse |
| select and middle button paste.) |
| |
| -sendalways Whenever the mouse enters the VNC viewer main |
| window, send the selection to the VNC server even if |
| it has not changed. This is like the Xt resource |
| translation SelectionToVNC(always) |
| |
| -recvtext str When cut text is received from the VNC server, |
| ssvncviewer will set both the X PRIMARY and the |
| X CLIPBOARD local selections. To control which |
| is set, specify 'str' as 'primary', 'clipboard', |
| or 'both' (the default.) |
| |
| -graball Grab the entire X server when in fullscreen mode, |
| needed by some old window managers like fvwm2. |
| |
| -popupfix Warp the popup back to the pointer position, |
| needed by some old window managers like fvwm2. |
| |
| -grabkbd Grab the X keyboard when in fullscreen mode, |
| needed by some window managers. Same as -grabkeyboard. |
| -grabkbd is the default, use -nograbkbd to disable. |
| |
| -bs, -nobs Whether or not to use X server Backingstore for the |
| main viewer window. The default is to not, mainly |
| because most Linux, etc, systems X servers disable |
| *all* Backingstore by default. To re-enable it put |
| |
| Option "Backingstore" |
| |
| in the Device section of /etc/X11/xorg.conf. |
| In -bs mode with no X server backingstore, whenever an |
| area of the screen is re-exposed it must go out to the |
| VNC server to retrieve the pixels. This is too slow. |
| |
| In -nobs mode, memory is allocated by the viewer to |
| provide its own backing of the main viewer window. This |
| actually makes some activities faster (changes in large |
| regions) but can appear to "flash" too much. |
| |
| -noshm Disable use of MIT shared memory extension (not recommended |
| ) |
| |
| -termchat Do the UltraVNC chat in the terminal vncviewer is in |
| instead of in an independent window. |
| |
| -unixpw str Useful for logging into x11vnc in -unixpw mode. "str" is a |
| string that allows many ways to enter the Unix Username |
| and Unix Password. These characters: username, newline, |
| password, newline are sent to the VNC server after any VNC |
| authentication has taken place. Under x11vnc they are |
| used for the -unixpw login. Other VNC servers could do |
| something similar. |
| |
| You can also indicate "str" via the environment |
| variable SSVNC_UNIXPW. |
| |
| Note that the Escape key is actually sent first to tell |
| x11vnc to not echo the Unix Username back to the VNC |
| viewer. Set SSVNC_UNIXPW_NOESC=1 to override this. |
| |
| If str is ".", then you are prompted at the command line |
| for the username and password in the normal way. If str is |
| "-" the stdin is read via getpass(3) for username@password. |
| Otherwise if str is a file, it is opened and the first line |
| read is taken as the Unix username and the 2nd as the |
| password. If str prefixed by "rm:" the file is removed |
| after reading. Otherwise, if str has a "@" character, |
| it is taken as username@password. Otherwise, the program |
| exits with an error. Got all that? |
| |
| -repeater str This is for use with UltraVNC repeater proxy described |
| here: http://www.uvnc.com/addons/repeater.html. The "str" |
| is the ID string to be sent to the repeater. E.g. ID:1234 |
| It can also be the hostname and port or display of the VNC |
| server, e.g. 12.34.56.78:0 or snoopy.com:1. Note that when |
| using -repeater, the host:dpy on the cmdline is the repeate |
| r |
| server, NOT the VNC server. The repeater will connect you. |
| |
| Example: vncviewer ... -repeater ID:3333 repeat.host:5900 |
| Example: vncviewer ... -repeater vhost:0 repeat.host:5900 |
| |
| Use, e.g., '-repeater SCIII=ID:3210' if the repeater is a |
| Single Click III (SSL) repeater (repeater_SSL.exe) and you |
| are passing the SSL part of the connection through stunnel, |
| socat, etc. This way the magic UltraVNC string 'testB' |
| needed to work with the repeater is sent to it. |
| |
| -rfbversion str Set the advertised RFB version. E.g.: -rfbversion 3.6 |
| For some servers, e.g. UltraVNC this needs to be done. |
| |
| -ultradsm UltraVNC has symmetric private key encryption DSM plugins: |
| http://www.uvnc.com/features/encryption.html. It is assumed |
| you are using a unix program (e.g. our ultravnc_dsm_helper) |
| to encrypt and decrypt the UltraVNC DSM stream. IN ADDITION |
| TO THAT supply -ultradsm to tell THIS viewer to modify the |
| RFB data sent so as to work with the UltraVNC Server. For |
| some reason, each RFB msg type must be sent twice under DSM |
| . |
| |
| -mslogon user Use Windows MS Logon to an UltraVNC server. Supply the |
| username or "1" to be prompted. The default is to |
| autodetect the UltraVNC MS Logon server and prompt for |
| the username and password. |
| |
| IMPORTANT NOTE: The UltraVNC MS-Logon Diffie-Hellman |
| exchange is very weak and can be brute forced to recover |
| your username and password in a few seconds of CPU time. |
| To be safe, be sure to use an additional encrypted tunnel |
| (e.g. SSL or SSH) for the entire VNC session. |
| |
| -chatonly Try to be a client that only does UltraVNC text chat. This |
| mode is used by x11vnc to present a chat window on the |
| physical X11 console (i.e. chat with the person at the |
| display). |
| |
| -env VAR=VALUE To save writing a shell script to set environment variables |
| , |
| specify as many as you need on the command line. For |
| example, -env SSVNC_MULTIPLE_LISTEN=MAX:5 -env EDITOR=vi |
| |
| -noipv6 Disable all IPv6 sockets. Same as VNCVIEWER_NO_IPV6=1. |
| |
| -noipv4 Disable all IPv4 sockets. Same as VNCVIEWER_NO_IPV4=1. |
| |
| -printres Print out the Ssvnc X resources (appdefaults) and then exit |
| You can save them to a file and customize them (e.g. the |
| keybindings and Popup menu) Then point to the file via |
| XENVIRONMENT or XAPPLRESDIR. |
| |
| -pipeline Like TurboVNC, request the next framebuffer update as soon |
| as possible instead of waiting until the end of the current |
| framebuffer update coming in. Helps 'pipeline' the updates |
| . |
| This is currently the default, use -nopipeline to disable. |
| |
| -appshare Enable features for use with x11vnc's -appshare mode where |
| instead of sharing the full desktop only the application's |
| windows are shared. Viewer multilisten mode is used to |
| create the multiple windows: -multilisten is implied. |
| See 'x11vnc -appshare -help' more information on the mode. |
| |
| Features enabled in the viewer under -appshare are: |
| Minimum extra text in the title, auto -ycrop is disabled, |
| x11vnc -remote_prefix X11VNC_APPSHARE_CMD: message channel, |
| x11vnc initial window position hints. See also Escape Keys |
| below for additional key and mouse bindings. |
| |
| -escape str This sets the 'Escape Keys' modifier sequence and enables |
| escape keys mode. When the modifier keys escape sequence |
| is held down, the next keystroke is interpreted locally |
| to perform a special action instead of being sent to the |
| remote VNC server. |
| |
| Use '-escape default' for the default modifier sequence. |
| (Unix: Alt_L,Super_L and MacOSX: Control_L,Meta_L) |
| |
| Here are the 'Escape Keys: Help+Set' instructions from the Popup Menu: |
| |
| Escape Keys: Enter a comma separated list of modifier keys to be the |
| 'escape sequence'. When these keys are held down, the next keystroke is |
| interpreted locally to invoke a special action instead of being sent to |
| the remote VNC server. In other words, a set of 'Hot Keys'. |
| |
| To enable or disable this, click on 'Escape Keys: Toggle' in the Popup. |
| |
| Here is the list of hot-key mappings to special actions: |
| |
| r: refresh desktop b: toggle bell c: toggle full-color |
| f: file transfer x: x11cursor z: toggle Tight/ZRLE |
| l: full screen g: graball e: escape keys dialog |
| s: scale dialog +: scale up (=) -: scale down (_) |
| t: text chat a: alphablend cursor |
| V: toggle viewonly Q: quit viewer 1 2 3 4 5 6: UltraVNC scale 1/n |
| |
| Arrow keys: pan the viewport about 10% for each keypress. |
| PageUp / PageDown: pan the viewport by a screenful vertically. |
| Home / End: pan the viewport by a screenful horizontally. |
| KeyPad Arrow keys: pan the viewport by 1 pixel for each keypress. |
| Dragging the Mouse with Button1 pressed also pans the viewport. |
| Clicking Mouse Button3 brings up the Popup Menu. |
| |
| The above mappings are *always* active in ViewOnly mode, unless you set the |
| Escape Keys value to 'never'. |
| |
| If the Escape Keys value below is set to 'default' then a default list of |
| of modifier keys is used. For Unix it is: Alt_L,Super_L and for MacOSX it |
| is Control_L,Meta_L. Note: the Super_L key usually has a Windows(TM) Flag |
| on it. Also note the _L and _R mean the key is on the LEFT or RIGHT side |
| of the keyboard. |
| |
| On Unix the default is Alt and Windows keys on Left side of keyboard. |
| On MacOSX the default is Control and Command keys on Left side of keyboard. |
| |
| Example: Press and hold the Alt and Windows keys on the LEFT side of the |
| keyboard and then press 'c' to toggle the full-color state. Or press 't' |
| to toggle the ultravnc Text Chat window, etc. |
| |
| To use something besides the default, supply a comma separated list (or a |
| single one) from: Shift_L Shift_R Control_L Control_R Alt_L Alt_R Meta_L |
| Meta_R Super_L Super_R Hyper_L Hyper_R or Mode_switch. |
| |
| |
| New Popup actions: |
| |
| ViewOnly: ~ -viewonly |
| Disable Bell: ~ -nobell |
| Cursor Shape: ~ -nocursorshape |
| X11 Cursor: ~ -x11cursor |
| Cursor Alphablend: ~ -alpha |
| Toggle Tight/Hextile: ~ -encodings hextile... |
| Toggle Tight/ZRLE: ~ -encodings zrle... |
| Toggle ZRLE/ZYWRLE: ~ -encodings zywrle... |
| Quality Level ~ -quality (both Tight and ZYWRLE) |
| Compress Level ~ -compresslevel |
| Disable JPEG: ~ -nojpeg (Tight) |
| Pipeline Updates ~ -pipeline |
| |
| Full Color as many colors as local screen allows. |
| Grey scale (16 & 8-bpp) ~ -grey, for low colors 16/8bpp modes only. |
| 16 bit color (BGR565) ~ -16bpp / -bgr565 |
| 8 bit color (BGR233) ~ -bgr233 |
| 256 colors ~ -bgr233 default # of colors. |
| 64 colors ~ -bgr222 / -use64 |
| 8 colors ~ -bgr111 / -use8 |
| Scale Viewer ~ -scale |
| Escape Keys: Toggle ~ -escape |
| Escape Keys: Help+Set ~ -escape |
| Set Y Crop (y-max) ~ -ycrop |
| Set Scrollbar Width ~ -sbwidth |
| XGrabServer ~ -graball |
| |
| UltraVNC Extensions: |
| |
| Set 1/n Server Scale Ultravnc ext. Scale desktop by 1/n. |
| Text Chat Ultravnc ext. Do Text Chat. |
| File Transfer Ultravnc ext. File xfer via Java helper. |
| Single Window Ultravnc ext. Grab and view a single window. |
| (select then click on the window you want). |
| Disable Remote Input Ultravnc ext. Try to prevent input and |
| viewing of monitor at physical display. |
| |
| Note: the Ultravnc extensions only apply to servers that support |
| them. x11vnc/libvncserver supports some of them. |
| |
| Send Clipboard not Primary ~ -sendclipboard |
| Send Selection Every time ~ -sendalways |
| |
| Nearly all of these can be changed dynamically in the Popup menu |
| (press F8 for it): |
| |
| [viewer_menu.gif] [unixviewer.jpg] |
| |
| _________________________________________________________________ |
| |
| Windows: |
| |
| For Windows, SSL Viewer support is provided by a GUI Windows/ssvnc.exe |
| that prompts for the VNC display and then starts up STUNNEL followed |
| by the Stock TightVNC Windows Viewer. Both are bundled in the package |
| for your convenience. The GUI has other useful features. When the |
| connection is finished, you will be asked if you want to terminate the |
| STUNNEL program. For SSH connections from Windows the GUI will use |
| PLINK instead of STUNNEL. |
| |
| Unix and Mac OS X: |
| |
| Run the GUI (ssvnc, see above) and let me know how it goes. |
| _________________________________________________________________ |
| |
| Hopefully this tool will make it convenient for people to help test |
| and use the built-in SSL support in x11vnc. Extra testing of this |
| feature is much appreciated!! Thanks. |
| |
| Please Help Test the newly added features: |
| * Automatic Service tunnelling via SSH for CUPS and SMB Printing |
| * ESD/ARTSD Audio |
| * SMB (Windows/Samba) filesystem mounting |
| |
| These allow you to print from the remote (VNC Server) machine to local |
| printers, listen to sounds (with some limitations) from the remote VNC |
| Server machine, and to mount your local Windows or Samba shares on the |
| remote VNC Server machine. Basically these new features try to |
| automate the tricks described here: |
| http://www.karlrunge.com/x11vnc/faq.html#faq-smb-shares |
| http://www.karlrunge.com/x11vnc/faq.html#faq-cups |
| http://www.karlrunge.com/x11vnc/faq.html#faq-sound |
| _________________________________________________________________ |
| |
| Downloading: Downloads for this project are hosted at Sourceforge.net. |
| |
| Choose the archive file bundle that best suits you (e.g. no source |
| code, windows only, unix only, zip, tar etc). |
| |
| A quick guide: |
| |
| On some flavor of Unix, e.g. Linux or Solaris? Use |
| "ssvnc_unix_only" (or "ssvnc_no_windows" to recompile). |
| On Mac OS X? Use "ssvnc_no_windows". |
| On Windows? Use "ssvnc_windows_only". |
| ssvnc_windows_only-1.0.28.zip Windows Binaries Only. No source included |
| (6.2MB) |
| ssvnc_no_windows-1.0.28.tar.gz Unix and Mac OS X Only. No Windows binarie |
| s. Source included. (10.1MB) |
| ssvnc_unix_only-1.0.28.tar.gz Unix Binaries Only. No source included |
| . (7.2MB) |
| ssvnc_unix_minimal-1.0.28.tar.gz Unix Minimal. You must supply your own vn |
| cviewer and stunnel. (0.2MB) |
| |
| ssvnc-1.0.28.tar.gz All Unix, Mac OS X, and Windows binaries a |
| nd source TGZ. (16.1MB) |
| ssvnc-1.0.28.zip All Unix, Mac OS X, and Windows binaries a |
| nd source ZIP. (16.4MB) |
| ssvnc_all-1.0.28.zip All Unix, Mac OS X, and Windows binaries a |
| nd source AND full archives in the zip dir. (19.2MB) |
| |
| |
| Here is a conventional source tarball: |
| ssvnc-1.0.28.src.tar.gz Conventional Source for SSVNC GUI and Unix |
| VNCviewer (0.5MB) |
| |
| it will be of use to those who do not want the SSVNC |
| "one-size-fits-all" bundles. For example, package/distro maintainers |
| will find this more familiar and useful to them (i.e. they run: "make |
| config; make all; make install"). Note that it does not include the |
| stunnel source, and so has a dependency that the system stunnel is |
| installed. |
| |
| Read the README.src file for more information on using the |
| conventional source tarball. |
| |
| |
| Note: even with the Unix bundles, e.g. "ssvnc_no_windows" or |
| "ssvnc_all", you may need to run the "./build.unix" script in the top |
| directory to recompile for your operating system. |
| |
| Here are the corresponding 1.0.29 development bundles (Please help |
| test them): |
| |
| ssvnc_windows_only-1.0.29.zip |
| ssvnc_no_windows-1.0.29.tar.gz |
| ssvnc_unix_only-1.0.29.tar.gz |
| ssvnc_unix_minimal-1.0.29.tar.gz |
| |
| ssvnc-1.0.29.tar.gz |
| ssvnc-1.0.29.zip |
| ssvnc_all-1.0.29.zip |
| |
| ssvnc-1.0.29.src.tar.gz Conventional Source for SSVNC GUI and Unix |
| VNCviewer (0.5MB) |
| |
| |
| For any Unix system, a self-extracting and running file for the |
| "ssvnc_unix_minimal" package is here: ssvnc. Save it as filename |
| "ssvnc", type "chmod 755 ./ssvnc", and then launch the GUI via typing |
| "./ssvnc". Note that this "ssvnc_unix_minimal" mode requires you |
| install the "stunnel" and "vncviewer" programs externally (for |
| example, install your distros' versions, e.g. on debian: "apt-get |
| install stunnel4 xtightvncviewer".) It will work, but many of the |
| SSVNC features will be missing. |
| |
| Previous releases: |
| Release 1.0.18 at Sourceforge.net |
| Release 1.0.19 at Sourceforge.net |
| Release 1.0.20 at Sourceforge.net |
| Release 1.0.21 at Sourceforge.net |
| Release 1.0.22 at Sourceforge.net |
| Release 1.0.23 at Sourceforge.net |
| Release 1.0.24 at Sourceforge.net |
| Release 1.0.25 at Sourceforge.net |
| Release 1.0.26 at Sourceforge.net |
| Release 1.0.27 at Sourceforge.net |
| Release 1.0.28 at Sourceforge.net |
| |
| |
| Please help test the UltraVNC File Transfer support in the native Unix |
| VNC viewer! Let us know how it went. |
| |
| Current Unix binaries in the archives: |
| Linux.i686 |
| Linux.x86_64 |
| Linux.ppc64 X (removed) |
| Linux.alpha X (removed) |
| SunOS.sun4u |
| SunOS.sun4m |
| SunOS.i86pc |
| Darwin.Power.Macintosh |
| Darwin.i386 |
| HP-UX.9000 X (removed) |
| FreeBSD.i386 X (removed) |
| NetBSD.i386 X (removed) |
| OpenBSD.i386 X (removed) |
| |
| (some of these are out of date, marked with 'X' above, because I no |
| longer have access to machines running those OS's. Use the |
| "build.unix" script to recompile on your system). |
| |
| Note: some of the above binaries depend on libssl.so.0.9.7, whereas |
| some recent distros only provide libssl.so.0.9.8 by default (for |
| compatibility reasons they should install both by default but not all |
| do). So you may need to instruct your distro to install the 0.9.7 |
| library (it is fine to have both runtimes installed simultaneously |
| since the libraries have different names). Update: I now try to |
| statically link libssl.a for all of the binaries in the archive. |
| |
| You can also run the included build.unix script to try to |
| automatically build the binaries if your OS is not in the above list |
| or the included binary does not run properly on your system. Let me |
| know how that goes. |
| _________________________________________________________________ |
| |
| IMPORTANT: there may be restrictions for you to download, use, or |
| redistribute the above because of cryptographic software they contain |
| or for other reasons. Please check out your situation and information |
| at the following and related sites: |
| http://stunnel.mirt.net |
| http://www.stunnel.org |
| http://www.openssl.org |
| http://www.chiark.greenend.org.uk/~sgtatham/putty/ |
| http://www.tightvnc.com |
| http://www.realvnc.com |
| http://sourceforge.net/projects/cotvnc/ |
| _________________________________________________________________ |
| |
| README: Here is the toplevel README from the bundle. |
| |
| ======================================================================= |
| http://www.karlrunge.com/x11vnc/x11vnc_opts.html: |
| |
| |
| _________________________________________________________________ |
| |
| x11vnc: a VNC server for real X displays |
| |
| Here are all of x11vnc command line options: |
| % x11vnc -opts (see below for -help long descriptions) |
| |
| x11vnc: allow VNC connections to real X11 displays. 0.9.13 lastmod: 2010-12-27 |
| |
| x11vnc options: |
| -display disp -auth file -N |
| -autoport n -rfbport str -6 |
| -no6 -noipv6 -noipv4 |
| -reopen -reflect host:N -id windowid |
| -sid windowid -appshare -clip WxH+X+Y |
| -flashcmap -shiftcmap n -notruecolor |
| -advertise_truecolor -visual n -overlay |
| -overlay_nocursor -8to24 [opts] -24to32 |
| -scale fraction -geometry WxH -scale_cursor frac |
| -viewonly -shared -once |
| -forever -loop -timeout n |
| -sleepin n -inetd -tightfilexfer |
| -ultrafilexfer -http -http_ssl |
| -avahi -mdns -zeroconf |
| -connect string -connect_or_exit str -proxy string |
| -vncconnect -novncconnect -allow host1[,host2..] |
| -localhost -unixsock str -listen6 str |
| -nolookup -input string -grabkbd |
| -grabptr -ungrabboth -grabalways |
| -viewpasswd string -passwdfile filename -showrfbauth filename |
| -unixpw [list] -unixpw_nis [list] -unixpw_cmd cmd |
| -find -finddpy -listdpy |
| -findauth [disp] -create -xdummy |
| -xvnc -xvnc_redirect -xdummy_xvfb |
| -create_xsrv str -svc -svc_xdummy |
| -svc_xvnc -svc_xdummy_xvfb -xdmsvc |
| -sshxdmsvc -unixpw_system_greeter -redirect port |
| -display WAIT:... -vencrypt mode -anontls mode |
| -sslonly -dhparams file -nossl |
| -ssl [pem] -ssltimeout n -sslnofail |
| -ssldir dir -sslverify path -sslCRL path |
| -sslGenCA [dir] -sslGenCert type name -sslEncKey pem |
| -sslCertInfo pem -sslDelCert pem -sslScripts |
| -stunnel [pem] -stunnel3 [pem] -enc cipher:keyfile |
| -https [port] -httpsredir [port] -http_oneport |
| -ssh user@host:disp -usepw -storepasswd pass file |
| -nopw -accept string -afteraccept string |
| -gone string -users list -noshm |
| -flipbyteorder -onetile -solid [color] |
| -blackout string -xinerama -noxinerama |
| -xtrap -xrandr [mode] -rotate string |
| -padgeom WxH -o logfile -flag file |
| -rmflag file -rc filename -norc |
| -env VAR=VALUE -prog /path/to/x11vnc -h, -help |
| -?, -opts -V, -version -license |
| -dbg -q, -quiet -v, -verbose |
| -bg -modtweak -nomodtweak |
| -xkb -noxkb -capslock |
| -skip_lockkeys -noskip_lockkeys -skip_keycodes string |
| -sloppy_keys -skip_dups -noskip_dups |
| -add_keysyms -noadd_keysyms -clear_mods |
| -clear_keys -clear_all -remap string |
| -norepeat -repeat -nofb |
| -nobell -nosel -noprimary |
| -nosetprimary -noclipboard -nosetclipboard |
| -seldir string -cursor [mode] -nocursor |
| -cursor_drag -arrow n -noxfixes |
| -alphacut n -alphafrac fraction -alpharemove |
| -noalphablend -nocursorshape -cursorpos |
| -nocursorpos -xwarppointer -noxwarppointer |
| -always_inject -buttonmap string -nodragging |
| -ncache n -ncache_cr -ncache_no_moveraise |
| -ncache_no_dtchange -ncache_no_rootpixmap -ncache_keep_anims |
| -ncache_old_wm -ncache_pad n -debug_ncache |
| -wireframe [str] -nowireframe -nowireframelocal |
| -wirecopyrect mode -nowirecopyrect -debug_wireframe |
| -scrollcopyrect mode -noscrollcopyrect -scr_area n |
| -scr_skip list -scr_inc list -scr_keys list |
| -scr_term list -scr_keyrepeat lo-hi -scr_parms string |
| -fixscreen string -debug_scroll -noxrecord |
| -grab_buster -nograb_buster -debug_grabs |
| -debug_sel -pointer_mode n -input_skip n |
| -allinput -input_eagerly -speeds rd,bw,lat |
| -wmdt string -debug_pointer -debug_keyboard |
| -defer time -wait time -extra_fbur n |
| -wait_ui factor -setdefer n -nowait_bog |
| -slow_fb time -xrefresh time -nap |
| -nonap -sb time -readtimeout n |
| -ping n -nofbpm -fbpm |
| -nodpms -dpms -forcedpms |
| -clientdpms -noserverdpms -noultraext |
| -chatwindow -noxdamage -xd_area A |
| -xd_mem f -sigpipe string -threads |
| -nothreads -fs f -gaps n |
| -grow n -fuzz n -debug_tiles |
| -snapfb -rawfb string -freqtab file |
| -pipeinput cmd -macnodim -macnosleep |
| -macnosaver -macnowait -macwheel n |
| -macnoswap -macnoresize -maciconanim n |
| -macmenu -macuskbd -macnoopengl |
| -macnorawfb -gui [gui-opts] -remote command |
| -query variable -QD variable -sync |
| -query_retries str -remote_prefix str -noremote |
| -yesremote -unsafe -safer |
| -privremote -nocmds -allowedcmds list |
| -deny_all |
| |
| LibVNCServer options: |
| -rfbport port TCP port for RFB protocol |
| -rfbwait time max time in ms to wait for RFB client |
| -rfbauth passwd-file use authentication on RFB protocol |
| (use 'storepasswd' to create a password file) |
| -rfbversion 3.x Set the version of the RFB we choose to advertise |
| -permitfiletransfer permit file transfer support |
| -passwd plain-password use authentication |
| (use plain-password as password, USE AT YOUR RISK) |
| -deferupdate time time in ms to defer updates (default 40) |
| -deferptrupdate time time in ms to defer pointer updates (default none) |
| -desktop name VNC desktop name (default "LibVNCServer") |
| -alwaysshared always treat new clients as shared |
| -nevershared never treat new clients as shared |
| -dontdisconnect don't disconnect existing clients when a new non-shared |
| connection comes in (refuse new connection instead) |
| -httpdir dir-path enable http server using dir-path home |
| -httpport portnum use portnum for http connection |
| -enablehttpproxy enable http proxy support |
| -progressive height enable progressive updating for slow links |
| -listen ipaddr listen for connections only on network interface with |
| addr ipaddr. '-listen localhost' and hostname work too. |
| |
| libvncserver-tight-extension options: |
| -disablefiletransfer disable file transfer |
| -ftproot string set ftp root |
| |
| |
| |
| |
| % x11vnc -help |
| |
| x11vnc: allow VNC connections to real X11 displays. 0.9.13 lastmod: 2010-12-27 |
| |
| (type "x11vnc -opts" to just list the options.) |
| |
| Typical usage is: |
| |
| Run this command in a shell on the remote machine "far-host" |
| with X session you wish to view: |
| |
| x11vnc -display :0 |
| |
| Then run this in another window on the machine you are sitting at: |
| |
| vncviewer far-host:0 |
| |
| Once x11vnc establishes connections with the X11 server and starts listening |
| as a VNC server it will print out a string: PORT=XXXX where XXXX is typically |
| 5900 (the default VNC server port). One would next run something like |
| this on the local machine: "vncviewer hostname:N" where "hostname" is |
| the name of the machine running x11vnc and N is XXXX - 5900, i.e. usually |
| "vncviewer hostname:0". |
| |
| By default x11vnc will not allow the screen to be shared and it will exit |
| as soon as the client disconnects. See -shared and -forever below to override |
| these protections. See the FAQ for details how to tunnel the VNC connection |
| through an encrypted channel such as ssh(1). In brief: |
| |
| ssh -t -L 5900:localhost:5900 far-host 'x11vnc -localhost -display :0' |
| |
| vncviewer -encodings 'copyrect tight zrle hextile' localhost:0 |
| |
| Also, use of a VNC password (-rfbauth or -passwdfile) is strongly recommended. |
| |
| For additional info see: http://www.karlrunge.com/x11vnc/ |
| and http://www.karlrunge.com/x11vnc/faq.html |
| |
| |
| Config file support: if the file $HOME/.x11vncrc exists then each line in |
| it is treated as a single command line option. Disable with -norc. For |
| each option name, the leading character "-" is not required. E.g. a line |
| that is either "forever" or "-forever" may be used and are equivalent. |
| Likewise "wait 100" or "-wait 100" are acceptable and equivalent lines. |
| The "#" character comments out to the end of the line in the usual way |
| (backslash it for a literal). Leading and trailing whitespace is trimmed off. |
| Lines may be continued with a "\" as the last character of a line (it |
| becomes a space character). |
| |
| Options: |
| |
| -display disp X11 server display to connect to, usually :0. The X |
| server process must be running on same machine and |
| support MIT-SHM. Equivalent to setting the DISPLAY |
| environment variable to "disp". |
| |
| See the description below of the "-display WAIT:..." |
| extensions, where alias "-find" will find the user's |
| display automatically, and "-create" will create a |
| Xvfb session if no session is found. |
| |
| -auth file Set the X authority file to be "file", equivalent to |
| setting the XAUTHORITY environment variable to "file" |
| before startup. Same as -xauth file. See Xsecurity(7), |
| xauth(1) man pages for more info. |
| |
| Use '-auth guess' to have x11vnc use its -findauth |
| mechanism (described below) to try to guess the |
| XAUTHORITY filename and use it. |
| |
| XDM/GDM/KDM: if you are running x11vnc as root and want |
| to find the XAUTHORITY before anyone has logged into an |
| X session yet, use: x11vnc -env FD_XDM=1 -auth guess ... |
| (This will also find the XAUTHORITY if a user is already |
| logged into the X session.) When running as root, |
| FD_XDM=1 will be tried if the initial -auth guess fails. |
| |
| -N If the X display is :N, try to set the VNC display to |
| also be :N This just sets the -rfbport option to 5900+N |
| The program will exit immediately if that port is not |
| available. The -N option only works with normal -display |
| usage, e.g. :0 or :8, -N is ignored in the -display |
| WAIT:..., -create, -find, -svc, -redirect, etc modes. |
| |
| -autoport n Automatically probe for a free VNC port starting at n. |
| The default is to start probing at 5900. Use this to |
| stay away from other VNC servers near 5900. |
| |
| -rfbport str The VNC port to listen on (a LibVNCServer option), e.g. |
| 5900, 5901, etc. If specified as "-rfbport PROMPT" |
| then the x11vnc -gui is used to prompt the user to |
| enter the port number. |
| |
| -6 IPv6 listening support. In addition to IPv4, the |
| IPv6 address is listened on for incoming connections. |
| The same port number as IPv4 is used. |
| |
| NOTE: This x11vnc binary was compiled to have the |
| "-6" IPv6 listening mode ENABLED by default (CPPFLAGS |
| -DX11VNC_LISTEN6=1). So to disable IPv6 listening mode |
| you MUST supply the "-no6" option (see below.) |
| |
| The "-6" mode works for both normal connections and |
| -ssl encrypted ones. Nearly everything is supported |
| for the IPv6 case, but there are a few exceptions. |
| See -stunnel for its IPv6 support. |
| |
| Currently, for absolutely everything to work correctly |
| the machine may need to have some IPv4 support, at the |
| least for the loopback interface. However, for nearly |
| all usage modes no IPv4 support is required. See -nopiv4 |
| . |
| |
| If you have trouble compiling or running in IPv6 mode, |
| set -DX11VNC_IPV6=0 in CPPFLAGS when configuring to |
| disable IPv6 support. |
| |
| -no6 Disable IPv6 listening support (only useful if the |
| "-6" mode is compiled in to be the default; see the |
| X11VNC_LISTEN6 description above under "-6".) |
| |
| -noipv6 Do not try to use IPv6 for any listening or connecting |
| sockets. This includes both the listening service |
| port(s) and outgoing connections from -connect, |
| -connect_or_exit, or -proxy. Use this if you are having |
| problems due to IPv6. |
| |
| -noipv4 Do not try to use IPv4 for any listening or connecting |
| sockets. This is mainly for exploring the behavior of |
| x11vnc on an IPv6-only system, but may have other uses. |
| |
| -reopen If the X server connection is disconnected, try to |
| reopen the X display (up to one time.) This is of use |
| for display managers like GDM (KillInitClients option) |
| that kill x11vnc just after the user logs into the |
| X session. Note: the reopened state may be unstable. |
| Set X11VNC_REOPEN_DISPLAY=n to reopen n times and |
| set X11VNC_REOPEN_SLEEP_MAX to the number of seconds, |
| default 10, to keep trying to reopen the display (once |
| per second.) |
| |
| Update: as of 0.9.9, x11vnc tries to automatically avoid |
| being killed by the display manager by delaying creating |
| windows or using XFIXES. So you shouldn't need to use |
| KillInitClients=false as long as you log in quickly |
| enough (within 45 seconds of connecting.) You can |
| disable this by setting X11VNC_AVOID_WINDOWS=never. |
| You can also set it to the number of seconds to delay. |
| |
| -reflect host:N Instead of connecting to and polling an X display, |
| connect to the remote VNC server host:N and be a |
| reflector/repeater for it. This is useful for trying |
| to manage the case of many simultaneous VNC viewers |
| (e.g. classroom broadcasting) where, e.g. you put |
| a repeater on each network switch, etc, to improve |
| performance by distributing the load and network |
| traffic. Implies -shared (use -noshared as a later |
| option to disable). See the discussion below under |
| -rawfb vnc:host:N for more details. |
| |
| -id windowid Show the X window corresponding to "windowid" not |
| the entire display. New windows like popup menus, |
| transient toplevels, etc, may not be seen or may be |
| clipped. Disabling SaveUnders or BackingStore in the |
| X server may help show them. x11vnc may crash if the |
| window is initially partially obscured, changes size, |
| is iconified, etc. Some steps are taken to avoid this |
| and the -xrandr mechanism is used to track resizes. Use |
| xwininfo(1) to get the window id, or use "-id pick" |
| to have x11vnc run xwininfo(1) for you and extract |
| the id. The -id option is useful for exporting very |
| simple applications (e.g. the current view on a webcam). |
| -sid windowid As -id, but instead of using the window directly it |
| shifts a root view to it: this shows SaveUnders menus, |
| etc, although they will be clipped if they extend beyond |
| the window. |
| |
| -appshare Simple application sharing based on the -id/-sid |
| mechanism. Every new toplevel window that the |
| application creates induces a new viewer window via |
| a reverse connection. The -id/-sid and -connect |
| options are required. Run 'x11vnc -appshare -help' |
| for more info. |
| |
| -clip WxH+X+Y Only show the sub-region of the full display that |
| corresponds to the rectangle geometry with size WxH and |
| offset +X+Y. The VNC display has size WxH (i.e. smaller |
| than the full display). This also works for -id/-sid |
| mode where the offset is relative to the upper left |
| corner of the selected window. An example use of this |
| option would be to split a large (e.g. Xinerama) display |
| into two parts to be accessed via separate viewers by |
| running a separate x11vnc on each part. |
| |
| Use '-clip xinerama0' to clip to the first xinerama |
| sub-screen (if xinerama is active). xinerama1 for the |
| 2nd sub-screen, etc. This way you don't need to figure |
| out the WxH+X+Y of the desired xinerama sub-screen. |
| screens are sorted in increasing distance from the |
| (0,0) origin (I.e. not the Xserver's order). |
| |
| -flashcmap In 8bpp indexed color, let the installed colormap flash |
| as the pointer moves from window to window (slow). |
| Also try the -8to24 option to avoid flash altogether. |
| -shiftcmap n Rare problem, but some 8bpp displays use less than 256 |
| colorcells (e.g. 16-color grayscale, perhaps the other |
| bits are used for double buffering) *and* also need to |
| shift the pixels values away from 0, .., ncells. "n" |
| indicates the shift to be applied to the pixel values. |
| To see the pixel values set DEBUG_CMAP=1 to print out |
| a colormap histogram. Example: -shiftcmap 240 |
| -notruecolor For 8bpp displays, force indexed color (i.e. a colormap) |
| even if it looks like 8bpp TrueColor (rare problem). |
| -advertise_truecolor If the X11 display is indexed color, lie to clients |
| when they first connect by telling them it is truecolor. |
| To workaround RealVNC: inPF has colourMap but not 8bpp |
| Use '-advertise_truecolor reset' to reset client fb too. |
| |
| -visual n This option probably does not do what you think. |
| It simply *forces* the visual used for the framebuffer; |
| this may be a bad thing... (e.g. messes up colors or |
| cause a crash). It is useful for testing and for some |
| workarounds. n may be a decimal number, or 0x hex. |
| Run xdpyinfo(1) for the values. One may also use |
| "TrueColor", etc. see <X11/X.h> for a list. If the |
| string ends in ":m" then for better or for worse |
| the visual depth is forced to be m. You may want to |
| use -noshm when using this option (so XGetImage may |
| automatically translate the pixel data). |
| |
| -overlay Handle multiple depth visuals on one screen, e.g. 8+24 |
| and 24+8 overlay visuals (the 32 bits per pixel are |
| packed with 8 for PseudoColor and 24 for TrueColor). |
| |
| Currently -overlay only works on Solaris via |
| XReadScreen(3X11) and IRIX using XReadDisplay(3). |
| On Solaris there is a problem with image "bleeding" |
| around transient popup menus (but not for the menu |
| itself): a workaround is to disable SaveUnders |
| by passing the "-su" argument to Xsun (in |
| /etc/dt/config/Xservers). |
| |
| Use -overlay as a workaround for situations like these: |
| Some legacy applications require the default visual to |
| be 8bpp (8+24), or they will use 8bpp PseudoColor even |
| when the default visual is depth 24 TrueColor (24+8). |
| In these cases colors in some windows will be incorrect |
| in x11vnc unless -overlay is used. Another use of |
| -overlay is to enable showing the exact mouse cursor |
| shape (details below). |
| |
| Under -overlay, performance will be somewhat slower |
| due to the extra image transformations required. |
| For optimal performance do not use -overlay, but rather |
| configure the X server so that the default visual is |
| depth 24 TrueColor and try to have all apps use that |
| visual (e.g. some apps have -use24 or -visual options). |
| -overlay_nocursor Sets -overlay, but does not try to draw the exact mouse |
| cursor shape using the overlay mechanism. |
| |
| -8to24 [opts] Try this option if -overlay is not supported on your |
| OS, and you have a legacy 8bpp app that you want to |
| view on a multi-depth display with default depth 24 |
| (and is 32 bpp) OR have a default depth 8 display with |
| depth 24 overlay windows for some apps. This option |
| may not work on all X servers and hardware (tested |
| on XFree86/Xorg mga driver and Xsun). The "opts" |
| string is not required and is described below. |
| |
| This mode enables a hack where x11vnc monitors windows |
| within 3 levels from the root window. If it finds |
| any that are 8bpp it extracts the indexed color |
| pixel values using XGetImage() and then applies a |
| transformation using the colormap(s) to create TrueColor |
| RGB values that it in turn inserts into bits 1-24 of |
| the framebuffer. This creates a depth 24 "view" |
| of the display that is then exported via VNC. |
| |
| Conversely, for default depth 8 displays, the depth |
| 24 regions are read by XGetImage() and everything is |
| transformed and inserted into a depth 24 TrueColor |
| framebuffer. |
| |
| Note that even if there are *no* depth 24 visuals or |
| windows (i.e. pure 8bpp), this mode is potentially |
| an improvement over -flashcmap because it avoids the |
| flashing and shows each window in the correct color. |
| |
| This method works OK, but may still have bugs and it |
| does hog resources. If there are multiple 8bpp windows |
| using different colormaps, one may have to iconify all |
| but one for the colors to be correct. |
| |
| There may be painting errors for clipping and switching |
| between windows of depths 8 and 24. Heuristics are |
| applied to try to minimize the painting errors. One can |
| also press 3 Alt_L's in a row to refresh the screen |
| if the error does not repair itself. Also the option |
| -fixscreen 8=3.0 or -fixscreen V=3.0 may be used to |
| periodically refresh the screen at the cost of bandwidth |
| (every 3 sec for this example). |
| |
| The [opts] string can contain the following settings. |
| Multiple settings are separated by commas. |
| |
| For for some X servers with default depth 24 a |
| speedup may be achieved via the option "nogetimage". |
| This enables a scheme were XGetImage() is not used |
| to retrieve the 8bpp data. Instead, it assumes that |
| the 8bpp data is in bits 25-32 of the 32bit X pixels. |
| There is no requirement that the X server should put |
| the data there for our poll requests, but some do and |
| so the extra steps to retrieve it can be skipped. |
| Tested with mga driver with XFree86/Xorg. For the |
| default depth 8 case this option is ignored. |
| |
| To adjust how often XGetImage() is used to poll the |
| non-default visual regions for changes, use the option |
| "poll=t" where "t" is a floating point time. |
| (default: 0.05) |
| |
| Setting the option "level2" will limit the search |
| for non-default visual windows to two levels from the |
| root window. Do this on slow machines where you know |
| the window manager only imposes one extra window between |
| the app window and the root window. |
| |
| Also for very slow machines use "cachewin=t" |
| where t is a floating point amount of time to cache |
| XGetWindowAttributes results. E.g. cachewin=5.0. |
| This may lead to the windows being unnoticed for this |
| amount of time when deiconifying, painting errors, etc. |
| |
| While testing on a very old SS20 these options gave |
| tolerable response: -8to24 poll=0.2,cachewin=5.0. For |
| this machine -overlay is supported and gives better |
| response. |
| |
| Debugging for this mode can be enabled by setting |
| "dbg=1", "dbg=2", or "dbg=3". |
| |
| -24to32 Very rare problem: if the framebuffer (X display |
| or -rawfb) is 24bpp instead of the usual 32bpp, then |
| dynamically transform the pixels to 32bpp. This will be |
| slower, but can be used to work around problems where |
| VNC viewers cannot handle 24bpp (e.g. "main: setPF: |
| not 8, 16 or 32 bpp?"). See the FAQ for more info. |
| |
| In the case of -rawfb mode, the pixels are directly |
| modified by inserting a 0 byte to pad them out to 32bpp. |
| For X displays, a kludge is done that is equivalent to |
| "-noshm -visual TrueColor:32". (If better performance |
| is needed for the latter, feel free to ask). |
| |
| -scale fraction Scale the framebuffer by factor "fraction". Values |
| less than 1 shrink the fb, larger ones expand it. Note: |
| the image may not be sharp and response may be slower. |
| If "fraction" contains a decimal point "." it |
| is taken as a floating point number, alternatively |
| the notation "m/n" may be used to denote fractions |
| exactly, e.g. -scale 2/3 |
| |
| To scale asymmetrically in the horizontal and vertical |
| directions, specify a WxH geometry to stretch to: |
| e.g. '-scale 1024x768', or also '-scale 0.9x0.75' |
| |
| Scaling Options: can be added after "fraction" via |
| ":", to supply multiple ":" options use commas. |
| If you just want a quick, rough scaling without |
| blending, append ":nb" to "fraction" (e.g. -scale |
| 1/3:nb). No blending is the default for 8bpp indexed |
| color, to force blending for this case use ":fb". |
| |
| To disable -scrollcopyrect and -wirecopyrect under |
| -scale use ":nocr". If you need to to enable them use |
| ":cr" or specify them explicitly on the command line. |
| If a slow link is detected, ":nocr" may be applied |
| automatically. Default: :cr |
| |
| More esoteric options: for compatibility with vncviewers |
| the scaled width is adjusted to be a multiple of 4: |
| to disable this use ":n4". ":in" use interpolation |
| scheme even when shrinking, ":pad" pad scaled width |
| and height to be multiples of scaling denominator |
| (e.g. 3 for 2/3). |
| |
| -geometry WxH Same as -scale WxH |
| |
| -scale_cursor frac By default if -scale is supplied the cursor shape is |
| scaled by the same factor. Depending on your usage, |
| you may want to scale the cursor independently of the |
| screen or not at all. If you specify -scale_cursor |
| the cursor will be scaled by that factor. When using |
| -scale mode to keep the cursor at its "natural" size |
| use "-scale_cursor 1". Most of the ":" scaling |
| options apply here as well. |
| |
| -viewonly All VNC clients can only watch (default off). |
| -shared VNC display is shared, i.e. more than one viewer can |
| connect at the same time (default off). |
| -once Exit after the first successfully connected viewer |
| disconnects, opposite of -forever. This is the Default. |
| -forever Keep listening for more connections rather than exiting |
| as soon as the first client(s) disconnect. Same as -many |
| |
| To get the standard non-shared VNC behavior where when |
| a new VNC client connects the existing VNC client is |
| dropped use: -nevershared -forever This method can |
| also be used to guard against hung TCP connections that |
| do not go away. |
| |
| -loop Create an outer loop restarting the x11vnc process |
| whenever it terminates. -bg and -inetd are ignored |
| in this mode (however see -loopbg below). |
| |
| Useful for continuing even if the X server terminates |
| and restarts (at that moment the process will need |
| permission to reconnect to the new X server of course). |
| |
| Use, e.g., -loop100 to sleep 100 millisecs between |
| restarts, etc. Default is 2000ms (i.e. 2 secs) Use, |
| e.g. -loop300,5 to sleep 300 ms and only loop 5 times. |
| |
| If -loopbg (plus any numbers) is specified instead, |
| the "-bg" option is implied and the mode approximates |
| inetd(8) usage to some degree. In this case when |
| it goes into the background any listening sockets |
| (i.e. ports 5900, 5800) are closed, so the next one |
| in the loop can use them. This mode will only be of |
| use if a VNC client (the only client for that process) |
| is already connected before the process goes into the |
| background, for example, usage of -display WAIT:.., |
| -svc, and -connect can make use of this "poor man's" |
| inetd mode. The default wait time is 500ms in this |
| mode. This usage could use useful: -svc -bg -loopbg |
| |
| -timeout n Exit unless a client connects within the first n seconds |
| after startup. |
| |
| If there have been no connection attempts after n |
| seconds x11vnc exits immediately. If a client is |
| trying to connect but has not progressed to the normal |
| operating state, x11vnc gives it a few more seconds |
| to finish and exits if it does not make it to the |
| normal state. |
| |
| For reverse connections via -connect or -connect_or_exit |
| a timeout of n seconds will be set for all reverse |
| connects. If the connect timeout alarm goes off, |
| x11vnc will exit immediately. |
| |
| -sleepin n At startup sleep n seconds before proceeding (e.g. to |
| allow redirs and listening clients to start up) |
| |
| If a range is given: '-sleepin min-max', a random value |
| between min and max is slept. E.g. '-sleepin 0-20' and |
| '-sleepin 10-30'. Floats are allowed too. |
| |
| -inetd Launched by inetd(8): stdio instead of listening socket. |
| Note: if you are not redirecting stderr to a log file |
| (via shell 2> or -o option) you MUST also specify the -q |
| option, otherwise the stderr goes to the viewer which |
| will cause it to abort. Specifying both -inetd and -q |
| and no -o will automatically close the stderr. |
| |
| -tightfilexfer Enable the TightVNC file transfer extension. Note that |
| that when the -viewonly option is supplied all file |
| transfers are disabled. Also clients that log in |
| viewonly cannot transfer files. However, if the remote |
| control mechanism is used to change the global or |
| per-client viewonly state the filetransfer permissions |
| will NOT change. |
| |
| IMPORTANT: please understand if -tightfilexfer is |
| specified and you run x11vnc as root for, say, inetd |
| or display manager (gdm, kdm, ...) access and you do |
| not have it switch users via the -users option, then |
| VNC Viewers that connect are able to do filetransfer |
| reads and writes as *root*. |
| |
| Also, tightfilexfer is disabled in -unixpw mode. |
| |
| -ultrafilexfer Note: to enable UltraVNC filetransfer and to get it to |
| work you probably need to supply these LibVNCServer |
| options: "-rfbversion 3.6 -permitfiletransfer" |
| "-ultrafilexfer" is an alias for this combination. |
| |
| IMPORTANT: please understand if -ultrafilexfer is |
| specified and you run x11vnc as root for, say, inetd |
| or display manager (gdm, kdm, ...) access and you do |
| not have it switch users via the -users option, then |
| VNC Viewers that connect are able to do filetransfer |
| reads and writes as *root*. |
| |
| Note that sadly you cannot do both -tightfilexfer and |
| -ultrafilexfer at the same time because the latter |
| requires setting the version to 3.6 and tightvnc will |
| not do filetransfer when it sees that version number. |
| |
| -http Instead of using -httpdir (see below) to specify |
| where the Java vncviewer applet is, have x11vnc try |
| to *guess* where the directory is by looking relative |
| to the program location and in standard locations |
| (/usr/local/share/x11vnc/classes, etc). Under -ssl or |
| -stunnel the ssl classes subdirectory is sought. |
| -http_ssl As -http, but force lookup for ssl classes subdir. |
| |
| Note that for HTTPS, single-port Java applet delivery |
| you can set X11VNC_HTTPS_DOWNLOAD_WAIT_TIME to the |
| max number of seconds to wait for the applet download |
| to finish. The default is 15. |
| |
| -avahi Use the Avahi/mDNS ZeroConf protocol to advertise |
| this VNC server to the local network. (Related terms: |
| Rendezvous, Bonjour). Depending on your setup, you |
| may need to start avahi-daemon and open udp port 5353 |
| in your firewall. |
| |
| You can set X11VNC_AVAHI_NAME, X11VNC_AVAHI_HOST, |
| and/or X11VNC_AVAHI_PORT environment variables |
| to override the default values. For example: |
| -env X11VNC_AVAHI_NAME=wally |
| |
| If the avahi API cannot be found at build time, a helper |
| program like avahi-publish(1) or dns-sd(1) will be tried |
| |
| -mdns Same as -avahi. |
| -zeroconf Same as -avahi. |
| |
| -connect string For use with "vncviewer -listen" reverse connections. |
| If "string" has the form "host" or "host:port" |
| the connection is made once at startup. |
| |
| Use commas for a list of host's and host:port's. |
| E.g. -connect host1,host2 or host1:0,host2:5678. |
| Note that to reverse connect to multiple hosts at the |
| same time you will likely need to also supply: -shared |
| |
| Note that unlike most vnc servers, x11vnc will require a |
| password for reverse as well as for forward connections. |
| (provided password auth has been enabled, -rfbauth, etc) |
| If you do not want to require a password for reverse |
| connections set X11VNC_REVERSE_CONNECTION_NO_AUTH=1 in |
| your environment before starting x11vnc. |
| |
| If "string" contains "/" it is instead interpreted |
| as a file to periodically check for new hosts. |
| The first line is read and then the file is truncated. |
| Be careful about the location of this file if x11vnc |
| is running as root (e.g. via gdm(1), etc). |
| |
| |
| Repeater mode: Some services provide an intermediate |
| "vnc repeater": http://www.uvnc.com/addons/repeater.html |
| (and also http://koti.mbnet.fi/jtko/ for linux port) |
| that acts as a proxy/gateway. Modes like these require |
| an initial string to be sent for the reverse connection |
| before the VNC protocol is started. Here are the ways |
| to do this: |
| |
| -connect pre=some_string+host:port |
| -connect pre128=some_string+host:port |
| -connect repeater=ID:1234+host:port |
| -connect repeater=23.45.67.89::5501+host:port |
| |
| SSVNC notation is also supported: |
| |
| -connect repeater://host:port+ID:1234 |
| |
| As with normal -connect usage, if the repeater port is |
| not supplied 5500 is assumed. |
| |
| The basic idea is between the special tag, e.g. "pre=" |
| and "+" is the pre-string to be sent. Note that in |
| this case host:port is the repeater server, NOT the |
| vnc viewer. Somehow the pre-string tells the repeater |
| server how to find the vnc viewer and connect you to it. |
| |
| In the case pre=some_string+host:port, "some_string" |
| is simply sent. In the case preNNN=some_string+host:port |
| "some_string" is sent in a null padded buffer of |
| length NNN. repeater= is the same as pre250=, this is |
| the ultravnc repeater buffer size. |
| |
| Strings like "\n" and "\r", etc. are expanded to |
| newline and carriage return. "\c" is expanded to |
| "," since the connect string is comma separated. |
| |
| See also the -proxy option below for additional ways |
| to plumb reverse connections. |
| |
| Reverse SSL: using -connect in -ssl mode makes x11vnc |
| act as an SSL client (initiates SSL connection) rather |
| than an SSL server. The idea is x11vnc might be |
| connecting to stunnel on the viewer side with the |
| viewer in listening mode. If you do not want this |
| behavior, use -env X11VNC_DISABLE_SSL_CLIENT_MODE=1. |
| With this the viewer side can act as the SSL client |
| as it normally does for forward connections. |
| |
| Reverse SSL Repeater mode: This will work, but note |
| that if the VNC Client does any sort of a 'Fetch Cert' |
| action before connecting, then the Repeater will |
| likely drop the connection and both sides will need |
| to restart. Consider the use of -connect_or_exit |
| and -loop300,2 to have x11vnc reconnect once to the |
| repeater after the fetch. You will probably also want |
| to supply -sslonly to avoid x11vnc thinking the delay |
| in response means the connection is VeNCrypt. The env |
| var X11VNC_DISABLE_SSL_CLIENT_MODE=1 discussed above |
| may also be useful (i.e. the viewer can do a forward |
| connection as it normally does.) |
| |
| IPv6: as of x11vnc 0.9.10 the -connect option should |
| connect to IPv6 hosts properly. If there are problems |
| you can disable IPv6 by setting -DX11VNC_IPV6=0 |
| in CPPFLAGS when configuring. If there problems |
| connecting to IPv6 hosts consider a relay like the |
| included inet6to4 script or the -proxy option. |
| |
| -connect_or_exit str As with -connect, except if none of the reverse |
| connections succeed, then x11vnc shuts down immediately |
| |
| An easier to type alias for this option is '-coe' |
| |
| By the way, if you do not want x11vnc to listen on |
| ANY interface use -rfbport 0 which is handy for the |
| -connect_or_exit mode. |
| |
| -proxy string Use proxy in string (e.g. host:port) as a proxy for |
| making reverse connections (-connect or -connect_or_exit |
| options). |
| |
| Web proxies are supported, but note by default most of |
| them only support destination connections to ports 443 |
| or 563, so this might not be very useful (the viewer |
| would need to listen on that port or the router would |
| have to do a port redirection). |
| |
| A web proxy may be specified by either "host:port" |
| or "http://host:port" (the port is required even if |
| it is the common choices 80 or 8080) |
| |
| SOCKS4, SOCKS4a, and SOCKS5 are also supported. |
| SOCKS proxies normally do not have restrictions on the |
| destination port number. |
| |
| Use a format like this: socks://host:port or |
| socks5://host:port. Note that ssh -D does not support |
| SOCKS4a, so use socks5://. For socks:// SOCKS4 is used |
| on a numerical IP and "localhost", otherwise SOCKS4a |
| is used (and so the proxy tries to do the DNS lookup). |
| |
| An experimental mode is "-proxy http://host:port/..." |
| Note the "/" after the port that distinguishes it from |
| a normal web proxy. The port must be supplied even if |
| it is the default 80. For this mode a GET is done to |
| the supplied URL with the string host=H&port=P appended. |
| H and P will be the -connect reverse connect host |
| and port. Use the string "__END__" to disable the |
| appending. The basic idea here is that maybe some cgi |
| script provides the actual viewer hookup and tunnelling. |
| How to actually achieve this within cgi, php, etc. is |
| not clear... A custom web server or apache module |
| would be straight-forward. |
| |
| Another experimental mode is "-proxy ssh://user@host" |
| in which case a SSH tunnel is used for the proxying. |
| "user@" is not needed unless your unix username is |
| different on "host". For a non-standard SSH port |
| use ssh://user@host:port. If proxies are chained (see |
| next paragraph) then the ssh one must be the first one. |
| If ssh-agent is not active, then the ssh password needs |
| to be entered in the terminal where x11vnc is running. |
| Examples: |
| |
| -connect localhost:0 -proxy ssh://me@friends-pc:2222 |
| |
| -connect snoopy:0 -proxy ssh://ssh.company.com |
| |
| Multiple proxies may be chained together in case one |
| needs to ricochet off of a number of hosts to finally |
| reach the VNC viewer. Up to 3 may be chained, separate |
| them by commas in the order they are to be connected to. |
| E.g.: http://host1:port1,socks5://host2:port2 or three |
| like: first,second,third |
| |
| IPv6: as of x11vnc 0.9.10 the -proxy option should |
| connect to IPv6 hosts properly. If there are problems |
| you can disable IPv6 by setting -DX11VNC_IPV6=0 |
| in CPPFLAGS when configuring. If there problems |
| connecting to IPv6 hosts consider a relay like the |
| included inet6to4 script. |
| |
| -vncconnect Monitor the VNC_CONNECT X property set by the standard |
| -novncconnect VNC program vncconnect(1). When the property is |
| set to "host" or "host:port" establish a reverse |
| connection. Using xprop(1) instead of vncconnect may |
| work (see the FAQ). The -remote control mechanism uses |
| X11VNC_REMOTE channel, and this option disables/enables |
| it as well. Default: -vncconnect |
| |
| To use different names for these X11 properties (e.g. to |
| have separate communication channels for multiple |
| x11vnc's on the same display) set the VNC_CONNECT or |
| X11VNC_REMOTE env. vars. to the string you want, for |
| example: -env X11VNC_REMOTE=X11VNC_REMOTE_12345 |
| Both sides of the channel must use the same unique name. |
| The same can be done for the internal X11VNC_TICKER |
| property (heartbeat and timestamp) if desired. |
| |
| -allow host1[,host2..] Only allow client connections from hosts matching |
| the comma separated list of hostnames or IP addresses. |
| Can also be a numerical IP prefix, e.g. "192.168.100." |
| to match a simple subnet, for more control build |
| LibVNCServer with libwrap support (See the FAQ). If the |
| list contains a "/" it instead is a interpreted |
| as a file containing addresses or prefixes that is |
| re-read each time a new client connects. Lines can be |
| commented out with the "#" character in the usual way. |
| |
| -allow applies in -ssl mode, but not in -stunnel mode. |
| |
| IPv6: as of x11vnc 0.9.10 a host can be specified |
| in IPv6 numerical format, e.g. 2001:4860:b009::93. |
| |
| -localhost Basically the same as "-allow 127.0.0.1". |
| |
| Note: if you want to restrict which network interface |
| x11vnc listens on, see the -listen option below. |
| E.g. "-listen localhost" or "-listen 192.168.3.21". |
| As a special case, the option "-localhost" implies |
| "-listen localhost". |
| |
| A rare case, but for non-localhost -listen usage, if |
| you use the remote control mechanism (-R) to change |
| the -listen interface you may need to manually adjust |
| the -allow list (and vice versa) to avoid situations |
| where no connections (or too many) are allowed. |
| |
| If you do not want x11vnc to listen on ANY interface |
| (evidently you are using -connect or -connect_or_exit, |
| or plan to use remote control: -R connect:host), use |
| -rfbport 0 |
| |
| IPv6: if IPv6 is supported, this option automatically |
| implies the IPv6 loopback address '::1' as well. |
| |
| -unixsock str Listen on the unix socket (AF_UNIX) 'str' |
| for connections. This mode is for either local |
| connections or a tunnel endpoint where one wants the |
| file permission of the unix socket file to determine |
| what can connect to it. (This currently requires an |
| edit to libvnserver/rfbserver.c: comment out lines 310 |
| and 311, 'close(sock)' and 'return NULL' in rfbserver.c |
| after the setsockopt() call.) Note that to disable all |
| tcp listening ports specify '-rfbport 0' and should be |
| useful with this mode. Example: |
| mkdir ~/s; chmod 700 ~/s; |
| x11vnc -unixsock ~/s/mysock -rfbport 0 ... |
| The SSVNC unix vncviewer can connect to unix sockets. |
| |
| -listen6 str When in IPv6 listen mode "-6", listen only on the |
| network interface with address "str". It also works |
| for link scope addresses (fe80::219:dbff:fee5:3f92%eth0) |
| and IPv6 hostname strings (e.g. ipv6.google.com.) |
| Use LibVNCServer -listen option for the IPv4 interface. |
| |
| -nolookup Do not use gethostbyname() or gethostbyaddr() to look up |
| host names or IP numbers. Use this if name resolution |
| is incorrectly set up and leads to long pauses as name |
| lookups time out, etc. |
| |
| -input string Fine tuning of allowed user input. If "string" does |
| not contain a comma "," the tuning applies only to |
| normal clients. Otherwise the part before "," is |
| for normal clients and the part after for view-only |
| clients. "K" is for Keystroke input, "M" for |
| Mouse-motion input, "B" for Button-click input, "C" |
| is for Clipboard input, and "F" is for File transfer |
| (ultravnc only). Their presence in the string enables |
| that type of input. E.g. "-input M" means normal |
| users can only move the mouse and "-input KMBCF,M" |
| lets normal users do anything and enables view-only |
| users to move the mouse. This option is ignored when |
| a global -viewonly is in effect (all input is discarded |
| in that case). |
| |
| -grabkbd When VNC viewers are connected, attempt to the grab |
| the keyboard so a (non-malicious) user sitting at the |
| physical display is not able to enter keystrokes. |
| This method uses XGrabKeyboard(3X11) and so it is |
| not secure and does not rule out the person at the |
| physical display injecting keystrokes by flooding the |
| server with them, grabbing the keyboard himself, etc. |
| Some degree of cooperation from the person at the |
| display is assumed. This is intended for remote |
| help-desk or educational usage modes. |
| |
| Note: on some recent (12/2010) X servers and/or |
| desktops, -grabkbd no longer works: it prevents the |
| window manager from resizing windows and similar things. |
| Try -ungrabboth below (might not work.) |
| |
| -grabptr As -grabkbd, but for the mouse pointer using |
| XGrabPointer(3X11). Unfortunately due to the way the X |
| server works, the mouse can still be moved around by the |
| user at the physical display, but he will not be able to |
| change window focus with it. Also some window managers |
| that call XGrabServer(3X11) for resizes, etc, will |
| act on the local user's input. Again, some degree of |
| cooperation from the person at the display is assumed. |
| |
| -ungrabboth Whenever there is any input (either keyboard or |
| pointer), ungrab *both* the keyboard and the pointer |
| while injecting the synthetic input. This is to allow |
| window managers, etc. a chance to grab. |
| |
| -grabalways Apply both -grabkbd and -grabptr even when no VNC |
| viewers are connected. If you only want one of them, |
| use the -R remote control to turn the other back on, |
| e.g. -R nograbptr. |
| |
| -viewpasswd string Supply a 2nd password for view-only logins. The -passwd |
| (full-access) password must also be supplied. |
| |
| -passwdfile filename Specify the LibVNCServer password via the first line |
| of the file "filename" (instead of via -passwd on |
| the command line where others might see it via ps(1)). |
| |
| See the descriptions below for how to supply multiple |
| passwords, view-only passwords, to specify external |
| programs for the authentication, and other features. |
| |
| If the filename is prefixed with "rm:" it will be |
| removed after being read. Perhaps this is useful in |
| limiting the readability of the file. In general, the |
| password file should not be readable by untrusted users |
| (BTW: neither should the VNC -rfbauth file: it is NOT |
| encrypted, only obscured with a fixed key). |
| |
| If the filename is prefixed with "read:" it will |
| periodically be checked for changes and reread. It is |
| guaranteed to be reread just when a new client connects |
| so that the latest passwords will be used. |
| |
| If "filename" is prefixed with "cmd:" then the |
| string after the ":" is run as an external command: |
| the output of the command will be interpreted as if it |
| were read from a password file (see below). If the |
| command does not exit with 0, then x11vnc terminates |
| immediately. To specify more than 1000 passwords this |
| way set X11VNC_MAX_PASSWDS before starting x11vnc. |
| The environment variables are set as in -accept. |
| |
| Note that due to the VNC protocol only the first 8 |
| characters of a password are used (DES key). |
| |
| If "filename" is prefixed with "custom:" then a |
| custom password checker is supplied as an external |
| command following the ":". The command will be run |
| when a client authenticates. If the command exits with |
| 0 the client is accepted, otherwise it is rejected. |
| The environment variables are set as in -accept. |
| |
| The standard input to the custom command will be a |
| decimal digit "len" followed by a newline. "len" |
| specifies the challenge size and is usually 16 (the |
| VNC spec). Then follows len bytes which is the random |
| challenge string that was sent to the client. This is |
| then followed by len more bytes holding the client's |
| response (i.e. the challenge string encrypted via DES |
| with the user password in the standard situation). |
| |
| The "custom:" scheme can be useful to implement |
| dynamic passwords or to implement methods where longer |
| passwords and/or different encryption algorithms |
| are used. The latter will require customizing the VNC |
| client as well. One could create an MD5SUM based scheme |
| for example. |
| |
| File format for -passwdfile: |
| |
| If multiple non-blank lines exist in the file they are |
| all taken as valid passwords. Blank lines are ignored. |
| Password lines may be "commented out" (ignored) if |
| they begin with the character "#" or the line contains |
| the string "__SKIP__". Lines may be annotated by use |
| of the "__COMM__" string: from it to the end of the |
| line is ignored. An empty password may be specified |
| via the "__EMPTY__" string on a line by itself (note |
| your viewer might not accept empty passwords). |
| |
| If the string "__BEGIN_VIEWONLY__" appears on a |
| line by itself, the remaining passwords are used for |
| viewonly access. For compatibility, as a special case |
| if the file contains only two password lines the 2nd |
| one is automatically taken as the viewonly password. |
| Otherwise the "__BEGIN_VIEWONLY__" token must be |
| used to have viewonly passwords. (tip: make the 3rd |
| and last line be "__BEGIN_VIEWONLY__" to have 2 |
| full-access passwords) |
| |
| -showrfbauth filename Print to the screen the obscured VNC password kept in |
| the rfbauth file "filename" and then exit. |
| |
| -unixpw [list] Use Unix username and password authentication. x11vnc |
| will use the su(1) program to verify the user's |
| password. [list] is an optional comma separated list |
| of allowed Unix usernames. If the [list] string begins |
| with the character "!" then the entire list is taken |
| as an exclude list. See below for per-user options |
| that can be applied. |
| |
| A familiar "login:" and "Password:" dialog is |
| presented to the user on a black screen inside the |
| vncviewer. The connection is dropped if the user fails |
| to supply the correct password in 3 tries or does not |
| send one before a 45 second timeout. Existing clients |
| are view-only during this period. |
| |
| If the first character received is "Escape" then the |
| unix username will not be displayed after "login:" |
| as it is typed. This could be of use for VNC viewers |
| that automatically type the username and password. |
| |
| Since the detailed behavior of su(1) can vary from |
| OS to OS and for local configurations, test the mode |
| before deployment to make sure it is working properly. |
| x11vnc will attempt to be conservative and reject a |
| login if anything abnormal occurs. |
| |
| One case to note: FreeBSD and the other BSD's by |
| default it is impossible for the user running x11vnc to |
| validate his *own* password via su(1) (commenting out |
| the pam_self.so entry in /etc/pam.d/su eliminates this |
| behavior). So the x11vnc login will always *FAIL* for |
| this case (even when the correct password is supplied). |
| |
| A possible workaround for this on *BSD would be to |
| start x11vnc as root with the "-users +nobody" option |
| to immediately switch to user nobody where the su'ing |
| will proceed normally. |
| |
| Another source of potential problems are PAM modules |
| that prompt for extra info, e.g. password aging modules. |
| These logins will fail as well even when the correct |
| password is supplied. |
| |
| **IMPORTANT**: to prevent the Unix password being sent |
| in *clear text* over the network, one of two schemes |
| will be enforced: 1) the -ssl builtin SSL mode, or 2) |
| require both -localhost and -stunnel be enabled. |
| |
| Method 1) ensures the traffic is encrypted between |
| viewer and server. A PEM file will be required, see the |
| discussion under -ssl below (under some circumstances |
| a temporary one can be automatically generated). |
| |
| Method 2) requires the viewer connection to appear |
| to come from the same machine x11vnc is running on |
| (e.g. from a ssh -L port redirection). And that the |
| -stunnel SSL mode be used for encryption over the |
| network. (see the description of -stunnel below). |
| |
| Note: as a convenience, if you ssh(1) in and start |
| x11vnc it will check if the environment variable |
| SSH_CONNECTION is set and appears reasonable. If it |
| does, then the -ssl or -stunnel requirement will be |
| dropped since it is assumed you are using ssh for the |
| encrypted tunnelling. -localhost is still enforced. |
| Use -ssl or -stunnel to force SSL usage even if |
| SSH_CONNECTION is set. |
| |
| To override the above restrictions you can set |
| environment variables before starting x11vnc: |
| |
| Set UNIXPW_DISABLE_SSL=1 to disable requiring either |
| -ssl or -stunnel (as under SSH_CONNECTION.) Evidently |
| you will be using a different method to encrypt the |
| data between the vncviewer and x11vnc: perhaps ssh(1) |
| or an IPSEC VPN. -localhost is still enforced (however, |
| see the next paragraph.) |
| |
| Set UNIXPW_DISABLE_LOCALHOST=1 to disable the -localhost |
| requirement in -unixpw modes. One should never do this |
| (i.e. allow the Unix passwords to be sniffed on the |
| network.) This also disables the localhost requirement |
| for reverse connections (see below.) |
| |
| Note that use of -localhost with ssh(1) (and no -unixpw) |
| is roughly the same as requiring a Unix user login |
| (since a Unix password or the user's public key |
| authentication is used by sshd on the machine where |
| x11vnc runs and only local connections from that machine |
| are accepted). |
| |
| Regarding reverse connections (e.g. -R connect:host |
| and -connect host), when the -localhost constraint is |
| in effect then reverse connections can only be used |
| to connect to the same machine x11vnc is running on |
| (default port 5500). Please use a ssh or stunnel port |
| redirection to the viewer machine to tunnel the reverse |
| connection over an encrypted channel. |
| |
| In -inetd mode the Method 1) will be enforced (not |
| Method 2). With -ssl in effect reverse connections |
| are disabled. If you override this via env. var, be |
| sure to also use encryption from the viewer to inetd. |
| Tip: you can also have your own stunnel spawn x11vnc |
| in -inetd mode (thereby bypassing inetd). See the FAQ |
| for details. |
| |
| The user names in the comma separated [list] may have |
| per-user options after a ":", e.g. "fred:opts" |
| where "opts" is a "+" separated list of |
| "viewonly", "fullaccess", "input=XXXX", or |
| "deny", e.g. "karl,wally:viewonly,boss:input=M". |
| For "input=" it is the K,M,B,C described under -input. |
| |
| If an item in the list is "*" that means those |
| options apply to all users. It ALSO implies all users |
| are allowed to log in after supplying a valid password. |
| Use "deny" to explicitly deny some users if you use |
| "*" to set a global option. If [list] begins with the |
| "!" character then "*" is ignored for checking if |
| the user is allowed, but the option values associated |
| with it do apply as normal. |
| |
| There are also some utilities for checking passwords |
| if [list] starts with the "%" character. See the |
| quick_pw() function for more details. Description: |
| "%-" or "%stdin" means read one line from stdin. |
| "%env" means it is in $UNIXPW env var. A leading |
| "%/" or "%." means read the first line from the |
| filename that follows after the % character. % by |
| itself means prompt for the username and password. |
| Otherwise: %user:pass E.g. -unixpw %fred:swordfish |
| For the other cases user:pass is read from the indicated |
| source. If the password is correct 'Y user' is printed |
| and the program exit code is 0. If the password is |
| incorrect it prints 'N user' and the exit code is 1. |
| If there is some other error the exit code is 2. |
| This feature enables x11vnc to be a general unix user |
| password checking tool; it could be used from scripts |
| or other programs. These % password checks also apply |
| to the -unixpw_nis and -unixpw_cmd options. |
| |
| For the % password check, if the env. var. UNIXPW_CMD |
| is set to a command then it is run as the user (assuming |
| the password is correct.) The output of the command is |
| not printed, the program or script must manage that by |
| some other means. The exit code of x11vnc will depend |
| on the exit code of the command that is run. |
| |
| Use -nounixpw to disable unixpw mode if it was enabled |
| earlier in the cmd line (e.g. -svc mode) |
| |
| -unixpw_nis [list] As -unixpw above, however do not use su(1) but rather |
| use the traditional getpwnam(3) + crypt(3) method to |
| verify passwords. All of the above -unixpw options and |
| constraints apply. |
| |
| This mode requires that the encrypted passwords be |
| readable. Encrypted passwords stored in /etc/shadow |
| will be inaccessible unless x11vnc is run as root. |
| |
| This is called "NIS" mode simply because in most |
| NIS setups user encrypted passwords are accessible |
| (e.g. "ypcat passwd") by an ordinary user and so that |
| user can authenticate ANY user. |
| |
| NIS is not required for this mode to work (only that |
| getpwnam(3) return the encrypted password is required), |
| but it is unlikely it will work (as an ordinary user) |
| for most modern environments unless NIS is available. |
| On the other hand, when x11vnc is run as root it will |
| be able to to access /etc/shadow even if NIS is not |
| available (note running as root is often done when |
| running x11vnc from inetd and xdm/gdm/kdm). |
| |
| Looked at another way, if you do not want to use the |
| su(1) method provided by -unixpw (i.e. su_verify()), you |
| can run x11vnc as root and use -unixpw_nis. Any users |
| with passwords in /etc/shadow can then be authenticated. |
| |
| In -unixpw_nis mode, under no circumstances is x11vnc's |
| user password verifying function based on su called |
| (i.e. the function su_verify() that runs /bin/su |
| in a pseudoterminal to verify passwords.) However, |
| if -unixpw_nis is used in conjunction with the -find |
| and -create -display WAIT:... modes then, if x11vnc is |
| running as root, /bin/su may be called externally to |
| run the find or create commands. |
| |
| -unixpw_cmd cmd As -unixpw above, however do not use su(1) but rather |
| run the externally supplied command "cmd". The first |
| line of its stdin will be the username and the second |
| line the received password. If the command exits |
| with status 0 (success) the VNC user will be accepted. |
| It will be rejected for any other return status. |
| |
| Dynamic passwords and non-unix passwords, e.g. LDAP, |
| can be implemented this way by providing your own custom |
| helper program. Note that the remote viewer is given 3 |
| tries to enter the correct password, and so the program |
| may be called in a row that many (or more) times. |
| |
| If a list of allowed users is needed to limit who can |
| log in, use -unixpw [list] in addition to this option. |
| |
| In FINDDISPLAY and FINDCREATEDISPLAY modes the "cmd" |
| will also be run with the RFB_UNIXPW_CMD_RUN env. var. |
| non-empty and set to the corresponding display |
| find/create command. The first two lines of input are |
| the username and passwd as in the normal case described |
| above. To support FINDDISPLAY and FINDCREATEDISPLAY, |
| "cmd" should run the requested command as the user |
| (and most likely refusing to run it if the password is |
| not correct.) Here is an example script (note it has |
| a hardwired bogus password "abc"!) |
| |
| #!/bin/sh |
| # Example x11vnc -unixpw_cmd script. |
| # Read the first two lines of stdin (user and passwd) |
| read user |
| read pass |
| |
| debug=0 |
| if [ $debug = 1 ]; then |
| echo "user: $user" 1>&2 |
| echo "pass: $pass" 1>&2 |
| env | egrep -i 'rfb|vnc' 1>&2 |
| fi |
| |
| # Check if the password is valid. |
| # (A real example would use ldap lookup, etc!) |
| if [ "X$pass" != "Xabc" ]; then |
| exit 1 # incorrect password |
| fi |
| |
| if [ "X$RFB_UNIXPW_CMD_RUN" = "X" ]; then |
| exit 0 # correct password |
| else |
| # Run the requested command (finddisplay) |
| if [ $debug = 1 ]; then |
| echo "run: $RFB_UNIXPW_CMD_RUN" 1>&2 |
| fi |
| exec /bin/su - "$user" -c "$RFB_UNIXPW_CMD_RUN" |
| fi |
| |
| In -unixpw_cmd mode, under no circumstances is x11vnc's |
| user password verifying function based on su called |
| (i.e. the function su_verify() that runs /bin/su in a |
| pseudoterminal to verify passwords.) It is up to the |
| supplied unixpw_cmd to do user switching if desired |
| and if it has the permissions to do so. |
| |
| -find Find the user's display using FINDDISPLAY. This |
| is an alias for "-display WAIT:cmd=FINDDISPLAY". |
| |
| Note: if a -display occurs later on the command line |
| it will override the -find setting. |
| |
| For this and the next few options see -display WAIT:... |
| below for all of the details. |
| |
| -finddpy Run the FINDDISPLAY program, print out the found |
| display (if any) and exit. Output is like: DISPLAY=:0.0 |
| DISPLAY=:0.0,XPID=12345 or DISPLAY=:0.0,VT=7. XPID is |
| the process ID of the found X server. VT is the Linux |
| virtual terminal of the X server. |
| -listdpy Have the FINDDISPLAY program list all of your displays |
| (i.e. all the X displays on the local machine that you |
| have access rights to). x11vnc then exits. |
| |
| -findauth [disp] Apply the -find/-finddpy heuristics to try to guess |
| the XAUTHORITY file for DISPLAY 'disp'. If 'disp' |
| is not supplied, then the value in the -display on |
| the cmdline is used; failing that $DISPLAY is used; |
| and failing that ":0" is used. x11vnc then exits. |
| |
| If nothing is printed out, that means no XAUTHORITY was |
| found for 'disp'; i.e. failure. If "XAUTHORITY=" |
| is printed out, that means use the default (i.e. do |
| not set XAUTHORITY). If "XAUTHORITY=/path/to/file" |
| is printed out, then use that file. |
| |
| XDM/GDM/KDM: if you are running x11vnc as root and want |
| to find the XAUTHORITY before anyone has logged into an |
| X session yet, use: x11vnc -env FD_XDM=1 -findauth ... |
| (This will also find the XAUTHORITY if a user is already |
| logged into the X session.) When running as root, |
| FD_XDM=1 will be tried if the initial -findauth fails. |
| |
| -create First try to find the user's display using FINDDISPLAY, |
| if that doesn't succeed create an X session via the |
| FINDCREATEDISPLAY method. This is an alias for |
| "-display WAIT:cmd=FINDCREATEDISPLAY-Xvfb". |
| |
| Note: if a -display occurs later on the command line |
| it will override the -create setting. |
| |
| SSH NOTE: for both -find and -create you can (should!) |
| add the "-localhost" option to force SSH tunnel access. |
| |
| -xdummy As in -create, except Xdummy instead of Xvfb. |
| -xvnc As in -create, except Xvnc instead of Xvfb. |
| -xvnc_redirect As in -create, except Xvnc.redirect instead of Xvfb. |
| -xdummy_xvfb Sets WAIT:cmd=FINDCREATEDISPLAY-Xdummy,Xvfb |
| |
| -create_xsrv str Sets WAIT:cmd=FINDCREATEDISPLAY-<str> Can be on cmdline |
| after anything that sets WAIT:.. and other things |
| (e.g. -svc, -xdmsvc) to adjust the X server list. |
| Example: -svc ... -create_xsrv Xdummy,X |
| |
| -svc Terminal services mode based on SSL access. Alias for |
| -display WAIT:cmd=FINDCREATEDISPLAY-Xvfb -unixpw -users |
| unixpw= -ssl SAVE Also "-service". |
| |
| Note: if a -display, -unixpw, -users, or -ssl occurs |
| later on the command line it will override the -svc |
| setting. |
| |
| -svc_xdummy As -svc except Xdummy instead of Xvfb. |
| -svc_xvnc As -svc except Xvnc instead of Xvfb. |
| -svc_xdummy_xvfb As -svc with Xdummy,Xvfb. |
| |
| -xdmsvc Display manager Terminal services mode based on SSL. |
| Alias for -display WAIT:cmd=FINDCREATEDISPLAY-Xvfb.xdmcp |
| -unixpw -users unixpw= -ssl SAVE Also "-xdm_service". |
| |
| Note: if a -display, -unixpw, -users, or -ssl occurs |
| later on the command line it will override the -xdmsvc |
| setting. |
| |
| To create a session a user will have to first log in |
| to the -unixpw dialog and then log in again to the |
| XDM/GDM/KDM prompt. Subsequent re-connections will |
| only require the -unixpw password. See the discussion |
| under -display WAIT:... for more details about XDM, |
| etc configuration. |
| |
| Remember to enable XDMCP in the xdm-config, gdm.conf, |
| or kdmrc configuration file. See -display WAIT: for |
| more info. |
| |
| -sshxdmsvc Display manager Terminal services mode based on SSH. |
| Alias for -display WAIT:cmd=FINDCREATEDISPLAY-Xvfb.xdmcp |
| -localhost. |
| |
| The -localhost option constrains connections to come |
| in via a SSH tunnel (which will require a login). |
| To create a session a user will also have to log into |
| the XDM GDM KDM prompt. Subsequent re-connections will |
| only only require the SSH login. See the discussion |
| under -display WAIT:... for more details about XDM, |
| etc configuration. |
| |
| Remember to enable XDMCP in the xdm-config, gdm.conf, |
| or kdmrc configuration file. See -display WAIT: for |
| more info. |
| |
| -unixpw_system_greeter Present a "Press 'Escape' for System Greeter" option |
| to the connecting VNC client in combined -unixpw |
| and xdmcp FINDCREATEDISPLAY modes (e.g. -xdmsvc). |
| |
| Normally in a -unixpw mode the VNC client must |
| supply a valid username and password to gain access. |
| However, if -unixpw_system_greeter is supplied AND |
| the FINDCREATEDISPLAY command matches 'xdmcp', then |
| the user has the option to press Escape and then get a |
| XDM/GDM/KDM login/greeter panel instead. They will then |
| supply a username and password directly to the greeter. |
| |
| Otherwise, in xdmcp FINDCREATEDISPLAY mode the user |
| must supply his username and password TWICE. First to |
| the initial unixpw login dialog, and second to the |
| subsequent XDM/GDM/KDM greeter. Note that if the user |
| re-connects and supplies his username and password in |
| the unixpw dialog the xdmcp greeter is skipped and |
| he is connected directly to his existing X session. |
| So the -unixpw_system_greeter option avoids the extra |
| password at X session creation time. |
| |
| Example: x11vnc -xdmsvc -unixpw_system_greeter |
| See -unixpw and -display WAIT:... for more info. |
| |
| The special options after a colon at the end of the |
| username (e.g. user:solid) described under -display |
| WAIT: are also applied in this mode if they are typed |
| in before the user hits Escape. The username is ignored |
| but the colon options are not. |
| |
| The default message is 2 lines in a small font, set |
| the env. var. X11VNC_SYSTEM_GREETER1=true for a 1 line |
| message in a larger font. |
| |
| If the user pressed Escape the FINDCREATEDISPLAY command |
| will be run with the env. var. X11VNC_XDM_ONLY=1. |
| |
| Remember to enable XDMCP in the xdm-config, gdm.conf, |
| or kdmrc configuration file. See -display WAIT: for |
| more info. |
| |
| -redirect port As in FINDCREATEDISPLAY-Xvnc.redirect mode except |
| redirect immediately (i.e. without X session finding |
| or creation) to a VNC server listening on port. You |
| can also supply host:port to redirect to a different |
| machine. |
| |
| If 0 <= port < 200 it is taken as a VNC display (5900 is |
| added to get the actual port), if port < 0 then -port |
| is used. |
| |
| Probably the only reason to use the -redirect option |
| is in conjunction with SSL support, e.g. -ssl SAVE. |
| This provides an easy way to add SSL encryption to a VNC |
| server that does not support SSL (e.g. Xvnc or vnc.so) |
| In fact, the protocol does not even need to be VNC, |
| and so "-rfbport port1 -ssl SAVE -redirect host:port2" |
| can act as a replacement for stunnel(1). |
| |
| This mode only allows one redirected connection. |
| The -forever option does not apply. Use -inetd or |
| -loop for persistent service. |
| |
| -display_WAIT :... A special usage mode for the normal -display option. |
| Useful with -unixpw, but can be used independently |
| of it. If the display string begins with WAIT: then |
| x11vnc waits until a VNC client connects before opening |
| the X display (or -rawfb device). |
| |
| This could be useful for delaying opening the display |
| for certain usage modes (say if x11vnc is started at |
| boot time and no X server is running or users logged |
| in yet). |
| |
| If the string is, e.g. WAIT:0.0 or WAIT:1, i.e. "WAIT" |
| in front of a normal X display, then that indicated |
| display is used. |
| |
| One can also insert a geometry between colons, e.g. |
| WAIT:1280x1024:... to set the size of the display the |
| VNC client first attaches to since some VNC viewers |
| will not automatically adjust to a new framebuffer size. |
| |
| A more interesting case is like this: |
| |
| WAIT:cmd=/usr/local/bin/find_display |
| |
| in which case the command after "cmd=" is run to |
| dynamically work out the DISPLAY and optionally the |
| XAUTHORITY data. The first line of the command output |
| must be of the form DISPLAY=<xdisplay>. On Linux |
| if the virtual terminal is known append ",VT=n" to |
| this string and the chvt(1) program will also be run. |
| Any remaining output is taken as XAUTHORITY data. |
| It can be either of the form XAUTHORITY=<file> or raw |
| xauthority data for the display. For example; |
| |
| xauth extract - $DISPLAY" |
| |
| NOTE: As specified in the previous paragraph, you can |
| supply your own WAIT:cmd=... program or script, BUT |
| there are two very useful *BUILT-IN* ones: FINDDISPLAY |
| (alias -find above) and FINDCREATEDISPLAY (alias -create |
| above.) Most people use these instead of creating |
| their own script. Read the following (especially the |
| BUILT-IN modes sections) to see how to configure these |
| two useful builtin -display WAIT: modes. |
| |
| In the case of -unixpw (and -unixpw_nis only if x11vnc |
| is running as root), then the cmd= command is run |
| as the user who just authenticated via the login and |
| password prompt. |
| |
| In the case of -unixpw_cmd, the commands will also be |
| run as the logged-in user, as long as the user-supplied |
| helper program supports RFB_UNIXPW_CMD_RUN (see the |
| -unixpw_cmd option.) |
| |
| Also in the case of -unixpw, the user logging in can |
| place a colon at the end of her username and supply |
| a few options: scale=, scale_cursor= (or sc=), solid |
| (or so), id=, clear_mods (or cm), clear_keys (or |
| ck), clear_all (or ca), repeat, speeds= (or sp=), |
| readtimeout= (or rd=), viewonly (or vo), nodisplay= |
| (or nd=), rotate= (or ro=), or noncache (or nc), |
| all separated by commas if there is more than one. |
| After the user logs in successfully, these options will |
| be applied to the VNC screen. For example, |
| |
| login: fred:scale=3/4,sc=1,repeat |
| Password: ... |
| |
| login: runge:sp=modem,rd=120,solid |
| |
| for convenience m/n implies scale= e.g. fred:3/4 If you |
| type and enter your password incorrectly, to retrieve |
| your long "login:" line press the Up arrow once |
| (before typing anything else). |
| |
| Most of these colon options only apply to the builtin |
| FINDDISPLAY and FINDCREATEDISPLAY modes, but note |
| that they are passed to the extrenal command in the |
| environment as well and so could be used. |
| |
| In the login panel, press F1 to get a list of the |
| available options that you can add after the username. |
| |
| Another option is "geom=WxH" or "geom=WxHxD" (or |
| ge=). This only has an effect in FINDCREATEDISPLAY |
| mode when a virtual X server such as Xvfb is going |
| to be created. It sets the width and height of |
| the new display, and optionally the color depth as |
| well. |
| |
| You can also supply "gnome", "kde", "twm", |
| "fvwm", "mwm", "dtwm", "wmaker", "xfce", |
| "lxde", "enlightenment", "Xsession", or |
| "failsafe" (same as "xterm") to have the created |
| display use that mode for the user session. |
| |
| Specify "tag=..." to set the unique FD_TAG desktop |
| session tag described below. Note: this option will |
| be ignored if the FD_TAG env. var. is already set or |
| if the viewer-side supplied value is not completely |
| composed of alphanumeric or '_' or '-' characters. |
| |
| User preferences file: Instead of having the user type |
| in geom=WxH,... etc. every time he logs in to find |
| or create his X session, if you set FD_USERPREFS to |
| a string that does not contain the "/" character, |
| then the user's home directory is prepended to that |
| string and if the file exists its first line is read |
| and appended to any options he supplied at the login: |
| prompt. For example -env FD_USERPREFS=.x11vnc_create |
| and the user put "geom=1600x1200" in his |
| ~/.x11vnc_create file. |
| |
| To disable the option setting set the environment |
| variable X11VNC_NO_UNIXPW_OPTS=1 before starting x11vnc. |
| To set any other options, the user can use the gui |
| (x11vnc -gui connect) or the remote control method |
| (x11vnc -R opt:val) during his VNC session. |
| |
| So we see the combination of -display WAIT:cmd=... and |
| -unixpw allows automatic pairing of an unix |
| authenticated VNC user with his desktop. This could |
| be very useful on SunRays and also any system where |
| multiple users share a given machine. The user does |
| not need to remember special ports or passwords set up |
| for his desktop and VNC. |
| |
| A nice way to use WAIT:cmd=... is out of inetd(8) |
| (it automatically forks a new x11vnc for each user). |
| You can have the x11vnc inetd spawned process run as, |
| say, root or nobody. When run as root (for either inetd |
| or display manager), you can also supply the option |
| "-users unixpw=" to have the x11vnc process switch to |
| the user as well. Note: there will be a 2nd SSL helper |
| process that will not switch, but it is only encoding |
| and decoding the encrypted stream at that point. |
| |
| BUILT-IN modes: |
| |
| -- Automatic Finding of User X Sessions -- |
| |
| As a special case, WAIT:cmd=FINDDISPLAY will run a |
| script that works on most Unixes to determine a user's |
| DISPLAY variable and xauthority data (see who(1)). |
| |
| NOTE: The option "-find" is an alias for this mode. |
| |
| To have this default script printed to stdout (e.g. for |
| customization) run with WAIT:cmd=FINDDISPLAY-print To |
| have the script run to print what display it would find |
| use "-finddpy" or WAIT:cmd=FINDDISPLAY-run |
| |
| The standard script runs xdpyinfo(1) run on potential |
| displays. If your X server(s) have a login greeter |
| that exclusively grabs the Xserver, then xdpyinfo |
| blocks forever and this mode will not work. See |
| www.karlrunge.com/x11vnc/faq.html#faq-display-manager |
| for how to disable this for dtgreet on Solaris and |
| possibly for other greeters. |
| |
| In -find/cmd=FINDDISPLAY mode, if you set FD_XDM=1, |
| e.g. 'x11vnc -env FD_XDM=1 -find ...' and x11vnc is |
| running as root (e.g. inetd) then it will try to find |
| the XAUTHORITY file of a running XDM/GDM/KDM login |
| greeter (i.e. no user has logged into an X session yet.) |
| |
| As another special case, WAIT:cmd=HTTPONCE will allow |
| x11vnc to service one http request and then exit. |
| This is usually done in -inetd mode to run on, say, |
| port 5800 and allow the Java vncviewer to be downloaded |
| by client web browsers. For example: |
| |
| 5815 stream tcp nowait root /usr/sbin/tcpd /.../x11vnc |
| \ |
| -inetd -q -http_ssl -prog /.../x11vnc \ |
| -display WAIT:cmd=HTTPONCE |
| |
| Where /.../x11vnc is the full path to x11vnc. |
| It is used in the Apache SSL-portal example (see FAQ). |
| |
| In this mode you can set X11VNC_SKIP_DISPLAY to a |
| comma separated list of displays (e.g. ":0,:1") to |
| ignore in the finding process. The ":" is optional. |
| Ranges n-m e.g. 0-20 can also be supplied. This string |
| can also be set by the connecting user via "nd=" |
| using "+" instead of "," If "nd=all" or you set |
| X11VNC_SKIP_DISPLAY=all then all display finding fails |
| as if you set X11VNC_FINDDISPLAY_ALWAYS_FAILS=1 (below.) |
| |
| On some systems lsof(1) can be very slow. Set the |
| env. var. FIND_DISPLAY_NO_LSOF=1 to skip using lsof to |
| try to find the Linux VT the X server is running on. |
| set FIND_DISPLAY_NO_VT_FIND=1 to avoid looking at all. |
| |
| -- Automatic Creation of User X Sessions -- |
| |
| An interesting option is WAIT:cmd=FINDCREATEDISPLAY |
| that is like FINDDISPLAY in that is uses the same method |
| to find an existing display. However, if it does not |
| find one it will try to *start* up an X server session |
| for the user. This is the only time x11vnc tries to |
| actually start up an X server. |
| |
| NOTE: The option "-create" is an alias for this mode. |
| |
| It will start looking for an open display number at :20 |
| Override via X11VNC_CREATE_STARTING_DISPLAY_NUMBER=n |
| By default 80 X displays are allowed (i.e. going to :99) |
| Override via X11VNC_CREATE_MAX_DISPLAYS=n |
| |
| For its heuristics, the create display script sets |
| LC_ALL=C so that command output is uniform. By default |
| it will try to restore LC_ALL right before starting the |
| user session. However, if you don't mind it keeping |
| LC_ALL=C set the env. var.: X11VNC_CREATE_LC_ALL_C_OK=1 |
| |
| By default FINDCREATEDISPLAY will try Xvfb and then |
| Xdummy: |
| |
| The Xdummy wrapper is part of the x11vnc source code |
| (x11vnc/misc/Xdummy) It should be available in PATH |
| and have run "Xdummy -install" once to create the |
| shared library. Xdummy only works on Linux. As of |
| 12/2009 it no longer needs to be run as root, and the |
| default is to not run as root. In some circumstances |
| permissions may require running it as root, in these |
| cases specify FD_XDUMMY_RUN_AS_ROOT=1, this is the same |
| as supplying -root to the Xdummy cmdline. |
| |
| Xvfb is available on most platforms and does not |
| require root. |
| |
| An advantage of Xdummy over Xvfb is that Xdummy supports |
| RANDR dynamic screen resizing. |
| |
| When x11vnc exits (i.e. user disconnects) the X |
| server session stays running in the background. |
| The FINDDISPLAY will find it directly next time. |
| The user must exit the X session in the usual way for |
| it to terminate (or kill the X server process if all |
| else fails). |
| |
| To troubleshoot the FINDCREATEDISPLAY mechanism, |
| set the following env. var. to an output log file, |
| e.g -env CREATE_DISPLAY_OUTPUT=/tmp/mydebug.txt |
| |
| So this is a somewhat odd mode for x11vnc in that it |
| will start up and poll virtual X servers! This can |
| be used from, say, inetd(8) to provide a means of |
| definitely getting a desktop (either real or virtual) |
| on the machine. E.g. a desktop service: |
| |
| 5900 stream tcp nowait root /usr/sbin/tcpd /.../x11vnc |
| -inetd -q -http -ssl SAVE -unixpw -users unixpw=\ |
| -passwd secret -prog /.../x11vnc \ |
| -display WAIT:cmd=FINDCREATEDISPLAY |
| |
| Where /.../x11vnc is the full path to x11vnc. |
| |
| See the -svc/-service option alias above. |
| |
| If for some reason you do not want x11vnc to ever |
| try to find an existing display set the env. var |
| X11VNC_FINDDISPLAY_ALWAYS_FAILS=1 (also -env ...) |
| This is the same as setting X11VNC_SKIP_DISPLAY=all or |
| supplying "nd=all" after "username:" |
| |
| Use WAIT:cmd=FINDCREATEDISPLAY-print to print out the |
| script that is used for this. |
| |
| You can specify the preferred X server order via e.g., |
| WAIT:cmd=FINDCREATEDISPLAY-Xdummy,Xvfb,X and/or leave |
| out ones you do not want. The the case "X" means try |
| to start up a real, hardware X server using xinit(1) |
| or startx(1). If there is already an X server running |
| the X case may only work on Linux (see startx(1)). |
| |
| "Xvnc" will start up a VNC X server (real- |
| or tight-vnc, e.g. use if Xvfb is not available). |
| "Xsrv" will start up the server program in the |
| variable "FD_XSRV" if it is non-empty. You can make |
| this be a wrapper script if you like (it must handle :N, |
| -geometry, and -depth and other X server options). |
| |
| You can set the environment variable FD_GEOM (or |
| X11VNC_CREATE_GEOM) to WxH or WxHxD to set the width |
| and height and optionally the color depth of the |
| created display. You can also set FD_SESS to be the |
| session (short name of the windowmanager: kde, gnome, |
| twm, failsafe, etc.). FD_OPTS contains extra options |
| to pass to the X server. You can also set FD_PROG to |
| be the full path to the session/windowmanager program. |
| |
| More FD tricks: FD_CUPS=port or FD_CUPS=host:port |
| will set the cups printing environment. Similarly for |
| FD_ESD=port or FD_ESD=host:port for esddsp sound |
| redirection. Set FD_EXTRA to a command to be run a |
| few seconds after the X server starts up. Set FD_TAG |
| to be a unique name for the session, it is set as an |
| X property, that makes FINDDISPLAY only find sessions |
| with that tag value. |
| |
| Set FD_XDMCP_IF to the network interface that the |
| display manager is running on; default is 'localhost' |
| but you may need to set it to '::1' on some IPv6 only |
| systems or misconfigured display managers. |
| |
| If you want the FINDCREATEDISPLAY session to contact an |
| XDMCP login manager (xdm/gdm/kdm) on the same machine, |
| then use "Xvfb.xdmcp" instead of "Xvfb", etc. |
| The user will have to supply his username and password |
| one more time (but he gets to select his desktop type |
| so that can be useful). For this to work, you will |
| need to enable localhost XDMCP (udp port 177) for the |
| display manager. This seems to be: |
| |
| for gdm in gdm.conf: Enable=true in section [xdmcp] |
| for kdm in kdmrc: Enable=true in section [Xdmcp] |
| for xdm in xdm-config: DisplayManager.requestPort: 177 |
| |
| See the shorthand options above "-svc", "-xdmsvc" |
| and "-sshxdmsvc" that specify the above options for |
| some useful cases. |
| |
| If you set the env. var WAITBG=1 x11vnc will go into |
| the background once listening in wait mode. |
| |
| Another special mode is FINDCREATEDISPLAY-Xvnc.redirect, |
| (or FINDDISPLAY-Xvnc.redirect). In this case it will |
| start up Xvnc as above if needed, but instead of |
| polling it in its normal way, it simply does a socket |
| redirection of the connected VNC viewer to the Xvnc. |
| |
| So in Xvnc.redirect x11vnc does no VNC but merely |
| transfers the data back and forth. This should be |
| faster then x11vnc's polling method, but not as fast |
| as connecting directly to the Xvnc with the VNC Viewer. |
| The idea here is to take advantage of x11vnc's display |
| finding/creating scheme, SSL, and perhaps a few others. |
| Most of x11vnc's options do not apply in this mode. |
| |
| Xvnc.redirect should also work for the vnc.so X server |
| module for the h/w display however it will work only |
| for finding the display and the user must already be |
| logged into the X console. |
| |
| -vencrypt mode The VeNCrypt extension to the VNC protocol allows |
| encrypted SSL/TLS connections. If the -ssl mode is |
| enabled, then VeNCrypt is enabled as well BY DEFAULT |
| (they both use a SSL/TLS tunnel, only the protocol |
| handshake is a little different.) |
| |
| To control when and how VeNCrypt is used, specify the |
| mode string. If mode is "never", then VeNCrypt is |
| not used. If mode is "support" (the default) then |
| VeNCrypt is supported. If mode is "only", then the |
| similar and older ANONTLS protocol is not simultaneously |
| supported. x11vnc's normal SSL mode (vncs://) will be |
| supported under -ssl unless you set mode to "force". |
| |
| If mode is prefixed with "nodh:", then Diffie Hellman |
| anonymous key exchange is disabled. If mode is prefixed |
| with "nox509:", then X509 key exchange is disabled. |
| |
| To disable all Anonymous Diffie-Hellman access |
| (susceptible to Man-In-The-Middle attack) you will need |
| to supply "-vencrypt nodh:support -anontls never" |
| or "-vencrypt nodh:only" |
| |
| If mode is prefixed with "newdh:", then new Diffie |
| Hellman parameters are generated for each connection |
| (this can be time consuming: 1-60 secs; see -dhparams |
| below for a faster way) rather than using the |
| fixed values in the program. Using fixed, publicly |
| known values is not known to be a security problem. |
| This setting applies to ANONTLS as well. |
| |
| Long example: -vencrypt newdh:nox509:support |
| |
| Also, if mode is prefixed with "plain:", then |
| if -unixpw mode is active the VeNCrypt "*Plain" |
| username+passwd method is enabled for Unix logins. |
| Otherwise in -unixpw mode the normal login panel is |
| provided. |
| |
| You *MUST* supply the -ssl option for VeNCrypt to |
| be active. The -vencrypt option only fine-tunes its |
| operation. |
| |
| -anontls mode The ANONTLS extension to the VNC protocol allows |
| encrypted SSL/TLS connections. If the -ssl mode is |
| enabled, then ANONTLS is enabled as well BY DEFAULT |
| (they both use a SSL/TLS tunnel, only the protocol |
| handshake is a little different.) |
| |
| ANONTLS is an older SSL/TLS mode introduced by vino. |
| |
| It is referred to as 'TLS' for its registered VNC |
| security-type name, but we use the more descriptive |
| 'ANONTLS' here because it provides only Anonymous |
| Diffie-Hellman encrypted connections, and hence no |
| possibility for certificate authentication. |
| |
| To control when and how ANONTLS is used, specify the |
| mode string. If mode is "never", then ANONTLS is not |
| used. If mode is "support" (the default) then ANONTLS |
| is supported. If mode is "only", then the similar |
| VeNCrypt protocol is not simultaneously supported. |
| x11vnc's normal SSL mode (vncs://) will be supported |
| under -ssl unless you set mode to "force". |
| |
| If mode is prefixed with "newdh:", then new Diffie |
| Hellman parameters are generated for each connection |
| (this can be time consuming: 1-60 secs; see -dhparams |
| below for a faster way) rather than using the |
| fixed values in the program. Using fixed, publicly |
| known values is not known to be a security problem. |
| This setting applies to VeNCrypt as well. See the |
| description of "plain:" under -vencrypt. |
| |
| Long example: -anontls newdh:plain:support |
| |
| You *MUST* supply the -ssl option for ANONTLS to |
| be active. The -anontls option only fine-tunes its |
| operation. |
| |
| -sslonly Same as: "-vencrypt never -anontls never" i.e. it |
| disables the VeNCrypt and ANONTLS encryption methods |
| and only allows standard SSL tunneling. You must also |
| supply the -ssl ... option (see below.) |
| |
| |
| -dhparams file For some operations a set of Diffie Hellman parameters |
| (prime and generator) is needed. If so, use the |
| parameters in "file". In particular, the VeNCrypt and |
| ANONTLS anonymous DH mode need them. By default a |
| fixed set is used. If you do not want to do that you |
| can specify "newdh:" to the -vencrypt and -anontls |
| options to generate a new set each session. If that |
| is too slow for you, use -dhparams file to a set you |
| created manually via "openssl dhparam -out file 1024" |
| |
| -nossl Disable the -ssl option (see below). Since -ssl is off |
| by default -nossl would only be used on the commandline |
| to unset any *earlier* -ssl option (or -svc...) |
| |
| -ssl [pem] Use the openssl library (www.openssl.org) to provide a |
| built-in encrypted SSL/TLS tunnel between VNC viewers |
| and x11vnc. This requires libssl support to be |
| compiled into x11vnc at build time. If x11vnc is not |
| built with libssl support it will exit immediately when |
| -ssl is prescribed. See the -stunnel option below for |
| an alternative. |
| |
| The VNC Viewer-side needs to support SSL/TLS as well. |
| See this URL and also the discussion below for |
| ideas on how to enable SSL support for the viewer: |
| http://www.karlrunge.com/x11vnc/faq.html#faq-ssl-tun |
| nel-viewers . x11vnc provides an SSL enabled Java |
| viewer applet in the classes/ssl directory (-http or |
| -httpdir options.) The SSVNC viewer package supports |
| SSL tunnels too. |
| |
| If the VNC Viewer supports VeNCrypt or ANONTLS (vino's |
| encryption mode) they are also supported by the -ssl |
| mode (see the -vencrypt and -anontls options for more |
| info; use -sslonly to disable both of them.) |
| |
| Use "-ssl /path/to/mycert.pem" to specify an SSL |
| certificate file in PEM format to use to identify and |
| provide a key for this server. See openssl(1) for more |
| info about PEMs and the -sslGenCert and "-ssl SAVE" |
| options below for how to create them. |
| |
| The connecting VNC viewer SSL tunnel can (at its option) |
| authenticate this server if it has the public key part |
| of the certificate (or a common certificate authority, |
| CA, is a more sophisticated way to verify this server's |
| cert, see -sslGenCA below). This authentication is |
| done to prevent Man-In-The-Middle attacks. Otherwise, |
| if the VNC viewer simply accepts this server's key |
| WITHOUT verification, the traffic is protected from |
| passive sniffing on the network, but *NOT* from |
| Man-In-The-Middle attacks. There are hacker tools |
| like dsniff/webmitm and cain that implement SSL |
| Man-In-The-Middle attacks. |
| |
| If [pem] is empty or the string "SAVE" then the |
| openssl(1) command must be available to generate the |
| certificate the first time. A self-signed certificate |
| is generated (see -sslGenCA and -sslGenCert for use |
| of a Certificate Authority.) It will be saved to the |
| file ~/.vnc/certs/server.pem. On subsequent calls if |
| that file already exists it will be used directly. |
| |
| Use "SAVE_NOPROMPT" to avoid being prompted to |
| protect the generated key with a passphrase. However in |
| -inetd and -bg modes there will be no prompting for a |
| passphrase in either case. |
| |
| If [pem] is "SAVE_PROMPT" the server.pem certificate |
| will be created based on your answers to its prompts for |
| all info such as OrganizationalName, CommonName, etc. |
| |
| Use "SAVE-<string>" and "SAVE_PROMPT-<string>" |
| to refer to the file ~/.vnc/certs/server-<string>.pem |
| instead (it will be generated if it does not already |
| exist). E.g. "SAVE-charlie" will store to the file |
| ~/.vnc/certs/server-charlie.pem |
| |
| Examples: x11vnc -ssl SAVE -display :0 ... |
| x11vnc -ssl SAVE-someother -display :0 ... |
| |
| If [pem] is "TMP" and the openssl(1) utility |
| command exists in PATH, then a temporary, self-signed |
| certificate will be generated for this session. If |
| openssl(1) cannot be used to generate a temporary |
| certificate x11vnc exits immediately. The temporary |
| cert will be discarded when x11vnc exits. |
| |
| If successful in using openssl(1) to generate a |
| temporary certificate in "SAVE" or "TMP" creation |
| modes, the public part of it will be displayed to stderr |
| (e.g. one could copy it to the client-side to provide |
| authentication of the server to VNC viewers.) |
| |
| NOTE: In "TMP" mode, unless you safely copy the |
| public part of the temporary Cert to the viewer for |
| authenticate *every time* (unlikely...), then only |
| passive sniffing attacks are prevented and you are |
| still open to Man-In-The-Middle attacks. This is |
| why the default "SAVE" mode is preferred (and more |
| sophisticated CA mode too). Only with saved keys AND |
| the VNC viewer authenticating them (via the public |
| certificate), are Man-In-The-Middle attacks prevented. |
| |
| If [pem] is "ANON" then the Diffie-Hellman anonymous |
| key exchange method is used. In this mode there |
| are *no* SSL certificates and so it is not possible |
| to authenticate either the VNC server or VNC client. |
| Thus only passive network sniffing attacks are avoided: |
| the "ANON" method is susceptible to Man-In-The-Middle |
| attacks. "ANON" is not recommended; instead use |
| a SSL PEM you created or the default "SAVE" method. |
| |
| See -ssldir below to use a directory besides the |
| default ~/.vnc/certs |
| |
| If your x11vnc binary was not compiled with OpenSSL |
| library support, use of the -ssl option will induce an |
| immediate failure and exit. For such binaries, consider |
| using the -stunnel option for SSL encrypted connections. |
| |
| Misc Info: In temporary cert creation mode "TMP", set |
| the env. var. X11VNC_SHOW_TMP_PEM=1 to have x11vnc print |
| out the entire certificate, including the PRIVATE KEY |
| part, to stderr. There are better ways to get/save this |
| info. See "SAVE" above and "-sslGenCert" below. |
| |
| -ssltimeout n Set SSL read timeout to n seconds. In some situations |
| (i.e. an iconified viewer in Windows) the viewer stops |
| talking and the connection is dropped after the default |
| timeout (25s for about the first minute, 43200s later). |
| Set to zero to poll forever. Set to a negative value |
| to use the builtin setting. |
| |
| Note that this value does NOT apply to the *initial* ssl |
| init connection. The default timeout for that is 20sec. |
| Use -env SSL_INIT_TIMEOUT=n to modify it. |
| |
| -sslnofail Exit at the first SSL connection failure. Useful when |
| scripting SSL connections (e.g. x11vnc is started via |
| ssh) and you do not want x11vnc waiting around for more |
| connections, tying up ports, etc. |
| |
| -ssldir dir Use "dir" as an alternate ssl certificate and key |
| management toplevel directory. The default is |
| ~/.vnc/certs |
| |
| This directory is used to store server and other |
| certificates and keys and also other materials. E.g. in |
| the simplest case, "-ssl SAVE" will store the x11vnc |
| server cert in dir/server.pem |
| |
| Use of alternate directories via -ssldir allows you to |
| manage multiple VNC Certificate Authority (CA) keys. |
| Another use is if ~/.vnc/cert is on an NFS share you |
| might want your certificates and keys to be on a local |
| filesystem to prevent network snooping (for example |
| -ssldir /var/lib/x11vnc-certs). |
| |
| -ssldir affects nearly all of the other -ssl* options, |
| e.g. -ssl SAVE, -sslGenCert, etc.. |
| |
| -sslverify path For either of the -ssl or -stunnel modes, use "path" |
| to provide certificates to authenticate incoming VNC |
| *Client* connections (normally only the server is |
| authenticated in SSL.) This can be used as a method |
| to replace standard password authentication of clients. |
| |
| If "path" is a directory it contains the client (or CA) |
| certificates in separate files. If path is a file, |
| it contains one or more certificates. See special tokens |
| below. These correspond to the "CApath = dir" and |
| "CAfile = file" stunnel options. See the stunnel(8) |
| manpage for details. |
| |
| Examples: |
| x11vnc -ssl -sslverify ~/my.crt |
| x11vnc -ssl -sslverify ~/my_pem_dir/ |
| |
| Note that if path is a directory, it must contain |
| the certs in separate files named like <HASH>.0, where |
| the value of <HASH> is found by running the command |
| "openssl x509 -hash -noout -in file.crt". Evidently |
| one uses <HASH>.1 if there is a collision... |
| |
| The the key-management utility "-sslCertInfo HASHON" |
| and "-sslCertInfo HASHOFF" will create/delete these |
| hashes for you automatically (via symlink) in the HASH |
| subdirs it manages. Then you can point -sslverify to |
| the HASH subdir. |
| |
| Special tokens: in -ssl mode, if "path" is not a file or |
| a directory, it is taken as a comma separated list of |
| tokens that are interpreted as follows: |
| |
| If a token is "CA" that means load the CA/cacert.pem |
| file from the ssl directory. If a token is "clients" |
| then all the files clients/*.crt in the ssl directory |
| are loaded. Otherwise the file clients/token.crt |
| is attempted to be loaded. As a kludge, use a token |
| like ../server-foo to load a server cert if you find |
| that necessary. |
| |
| Use -ssldir to use a directory different from the |
| ~/.vnc/certs default. |
| |
| Note that if the "CA" cert is loaded you do not need |
| to load any of the certs that have been signed by it. |
| You will need to load any additional self-signed certs |
| however. |
| |
| Examples: |
| x11vnc -ssl -sslverify CA |
| x11vnc -ssl -sslverify self:fred,self:jim |
| x11vnc -ssl -sslverify CA,clients |
| |
| Usually "-sslverify CA" is the most effective. |
| See the -sslGenCA and -sslGenCert options below for |
| how to set up and manage the CA framework. |
| |
| |
| |
| NOTE: the following utilities, -sslGenCA, -sslGenCert, |
| -sslEncKey, -sslCertInfo, and -sslCRL are provided for |
| completeness, but for casual usage they are overkill. |
| |
| They provide VNC Certificate Authority (CA) key creation |
| and server / client key generation and signing. So they |
| provide a basic Public Key management framework for |
| VNC-ing with x11vnc. (note that they require openssl(1) |
| be installed on the system) |
| |
| However, the simplest usage mode, "-ssl TMP" (where |
| x11vnc automatically generates its own, self-signed, |
| temporary key and the VNC viewers always accept it, |
| e.g. accepting via a dialog box) is probably safe enough |
| for most scenarios. CA management is not needed. |
| |
| To protect against Man-In-The-Middle attacks the "TMP" |
| mode can be improved by using "-ssl SAVE" (same as |
| "-ssl", i.e. the default) to have x11vnc create a |
| longer term self-signed certificate, and then (safely) |
| copy the corresponding public key cert to the desired |
| client machines (care must be taken the private key part |
| is not stolen; you will be prompted for a passphrase). |
| |
| So keep in mind no CA key creation or management |
| (-sslGenCA and -sslGenCert) is needed for either of |
| the above two common usage modes. |
| |
| One might want to use -sslGenCA and -sslGenCert |
| if you had a large number of VNC client and server |
| workstations. That way the administrator could generate |
| a single CA key with -sslGenCA and distribute its |
| certificate part to all of the workstations. |
| |
| Next, he could create signed VNC server keys |
| (-sslGenCert server ...) for each workstation or user |
| that then x11vnc would use to authenticate itself to |
| any VNC client that has the CA cert. |
| |
| Optionally, the admin could also make it so the |
| VNC clients themselves are authenticated to x11vnc |
| (-sslGenCert client ...) For this -sslverify would be |
| pointed to the CA cert (and/or self-signed certs). |
| |
| x11vnc will be able to use all of these cert and |
| key files. On the VNC client side, they will need to |
| be "imported" somehow. Web browsers have "Manage |
| Certificates" actions as does the Java applet plugin |
| Control Panel. stunnel can also use these files (see |
| the ss_vncviewer example script in the FAQ and SSVNC.) |
| |
| -sslCRL path Set the Certificate Revocation Lists (CRL) to "path". |
| This setting applies for both -ssl and -stunnel modes. |
| |
| If path is a file, the file contains one or more CRLs |
| in PEM format. If path is a directory, it contains |
| hash named files of CRLs in the usual OpenSSL manner. |
| See the OpenSSL and stunnel(8) documentation for |
| more info. |
| |
| This option only applies if -sslverify has been |
| supplied: it checks for revocation along the |
| certificate chain used to verify the VNC client. |
| The -sslCRL setting will be ignored when -sslverify is |
| not specified. |
| |
| Note that if a CRL's expiration date has passed, all |
| SSL connections will fail regardless of if they are |
| related to the subject of the CRL or not. |
| |
| Only rarely will one's x11vnc -ssl infrastructure be so |
| large that this option would be useful (since normally |
| maintaining the contents of the -sslverify file or |
| directory should be enough.) However, when using |
| x11vnc with a Certificate Authority (see -sslGenCA) |
| to authenticate Clients via SSL/TLS, the -sslCRL option |
| can be useful to revoke users' certs whose private SSL |
| keys were lost or stolen (e.g. laptop.) This way a new |
| CA cert+key does not need to be created and new signed |
| client keys generated and distributed to all users. |
| |
| To create a CRL file with revoked certificates the |
| commands 'openssl ca -revoke ...' and 'openssl ca |
| -gencrl ...' are useful. (Run them in ~/.vnc/certs) |
| |
| -sslGenCA [dir] Generate your own Certificate Authority private key, |
| certificate, and other files in directory [dir]. |
| x11vnc then exits. |
| |
| If [dir] is not supplied, a -ssldir setting is used, |
| or otherwise ~/.vnc/certs is used. |
| |
| This command also creates directories where server and |
| client certs and keys will be stored. The openssl(1) |
| program must be installed on the system and available |
| in PATH. |
| |
| After the CA files and directories are created the |
| x11vnc command exits; the VNC server is not run. |
| |
| You will be prompted for information to put into the CA |
| certificate. The info does not have to be accurate just |
| as long as clients accept the cert for VNC connections. |
| You will also need to supply a passphrase of at least |
| 4 characters for the CA private key. |
| |
| Once you have generated the CA you can distribute |
| its certificate part, [dir]/CA/cacert.pem, to other |
| workstations where VNC viewers will be run. One will |
| need to "import" this certificate in the applications, |
| e.g. Web browser, Java applet plugin, stunnel, etc. |
| Next, you can create and sign keys using the CA with |
| the -sslGenCert option below. |
| |
| Examples: |
| x11vnc -sslGenCA |
| x11vnc -sslGenCA ~/myCAdir |
| x11vnc -ssldir ~/myCAdir -sslGenCA |
| |
| (the last two lines are equivalent) |
| |
| -sslGenCert type name Generate a VNC server or client certificate and private |
| key pair signed by the CA created previously with |
| -sslGenCA. The openssl(1) program must be installed |
| on the system and available in PATH. |
| |
| After the Certificate is generated x11vnc exits; the |
| VNC server is not run. |
| |
| The type of key to be generated is the string "type". |
| It is either "server" (i.e. for use by x11vnc) or |
| "client" (for a VNC viewer). Note that typically |
| only "server" is used: the VNC clients authenticate |
| themselves by a non-public-key method (e.g. VNC or |
| unix password). "type" is required. |
| |
| An arbitrary default name you want to associate with |
| the key is supplied by the "name" string. You can |
| change it at the various prompts when creating the key. |
| "name" is optional. |
| |
| If name is left blank for clients keys then "nobody" |
| is used. If left blank for server keys, then the |
| primary server key: "server.pem" is created (this |
| is the saved one referenced by "-ssl SAVE" when the |
| server is started) |
| |
| If "name" begins with the string "self:" then |
| a self-signed certificate is created instead of one |
| signed by your CA key. |
| |
| If "name" begins with the string "req:" then only a |
| key (.key) and a certificate signing *request* (.req) |
| are generated. You can then send the .req file to |
| an external CA (even a professional one, e.g. Thawte) |
| and then combine the .key and the received cert into |
| the .pem file with the same basename. |
| |
| The distinction between "server" and "client" is |
| simply the choice of output filenames and sub-directory. |
| This makes it so the -ssl SAVE-name option can easily |
| pick up the x11vnc PEM file this option generates. |
| And similarly makes it easy for the -sslverify option |
| to pick up your client certs. |
| |
| There is nothing special about the filename or directory |
| location of either the "server" and "client" certs. |
| You can rename the files or move them to wherever |
| you like. |
| |
| Precede this option with -ssldir [dir] to use a |
| directory other than the default ~/.vnc/certs You will |
| need to run -sslGenCA on that directory first before |
| doing any -sslGenCert key creation. |
| |
| Note you cannot recreate a cert with exactly the same |
| distiguished name (DN) as an existing one. To do so, |
| you will need to edit the [dir]/CA/index.txt file to |
| delete the line. |
| |
| Similar to -sslGenCA, you will be prompted to fill |
| in some information that will be recorded in the |
| certificate when it is created. |
| |
| Tip: if you know the fully-qualified hostname other |
| people will be connecting to, you can use that as the |
| CommonName "CN" to avoid some applications (e.g. web |
| browsers and java plugin) complaining that it does not |
| match the hostname. |
| |
| You will also need to supply the CA private key |
| passphrase to unlock the private key created from |
| -sslGenCA. This private key is used to sign the server |
| or client certificate. |
| |
| The "server" certs can be used by x11vnc directly by |
| pointing to them via the -ssl [pem] option. The default |
| file will be ~/.vnc/certs/server.pem. This one would |
| be used by simply typing -ssl SAVE. The pem file |
| contains both the certificate and the private key. |
| server.crt file contains the cert only. |
| |
| The "client" cert + private key file will need |
| to be copied and imported into the VNC viewer |
| side applications (Web browser, Java plugin, |
| stunnel, etc.) Once that is done you can delete the |
| "client" private key file on this machine since |
| it is only needed on the VNC viewer side. The, |
| e.g. ~/.vnc/certs/clients/<name>.pem contains both |
| the cert and private key. The <name>.crt contains the |
| certificate only. |
| |
| NOTE: It is very important to know one should |
| generate new keys with a passphrase. Otherwise if an |
| untrusted user steals the key file he could use it to |
| masquerade as the x11vnc server (or VNC viewer client). |
| You will be prompted whether to encrypt the key with |
| a passphrase or not. It is recommended that you do. |
| One inconvenience to a passphrase is that it must |
| be typed in EVERY time x11vnc or the client app is |
| started up. |
| |
| Examples: |
| |
| x11vnc -sslGenCert server |
| x11vnc -ssl SAVE -display :0 ... |
| |
| and then on viewer using ss_vncviewer stunnel wrapper |
| (see the FAQ): |
| ss_vncviewer -verify ./cacert.crt hostname:0 |
| |
| (this assumes the cacert.crt cert from -sslGenCA |
| was safely copied to the VNC viewer machine where |
| ss_vncviewer is run) |
| |
| Example using a name: |
| |
| x11vnc -sslGenCert server charlie |
| x11vnc -ssl SAVE-charlie -display :0 ... |
| |
| Example for a client certificate (rarely used): |
| |
| x11vnc -sslGenCert client roger |
| scp ~/.vnc/certs/clients/roger.pem somehost:. |
| rm ~/.vnc/certs/clients/roger.pem |
| |
| x11vnc is then started with the option -sslverify |
| ~/.vnc/certs/clients/roger.crt (or simply -sslverify |
| roger), and on the viewer user on somehost could do |
| for example: |
| |
| ss_vncviewer -mycert ./roger.pem hostname:0 |
| |
| If you set the env. var REQ_ARGS='...' it will be |
| passed to openssl req(1). A common use would be |
| REQ_ARGS='-days 1095' to bump up the expiration date |
| (3 years in this case). |
| |
| -sslEncKey pem Utility to encrypt an existing PEM file with a |
| passphrase you supply when prompted. For that key to be |
| used (e.g. by x11vnc) the passphrase must be supplied |
| each time. |
| |
| The "SAVE" notation described under -ssl applies as |
| well. (precede this option with -ssldir [dir] to refer |
| a directory besides the default ~/.vnc/certs) |
| |
| The openssl(1) program must be installed on the system |
| and available in PATH. After the Key file is encrypted |
| the x11vnc command exits; the VNC server is not run. |
| |
| Examples: |
| x11vnc -sslEncKey /path/to/foo.pem |
| x11vnc -sslEncKey SAVE |
| x11vnc -sslEncKey SAVE-charlie |
| |
| -sslCertInfo pem Prints out information about an existing PEM file. |
| In addition the public certificate is also printed. |
| The openssl(1) program must be in PATH. Basically the |
| command "openssl x509 -text" is run on the pem. |
| |
| After the info is printed the x11vnc command exits; |
| the VNC server is not run. |
| |
| The "SAVE" notation described under -ssl applies |
| as well. |
| |
| Using "LIST" will give a list of all certs being |
| managed (in the ~/.vnc/certs dir, use -ssldir to refer |
| to another dir). "ALL" will print out the info for |
| every managed key (this can be very long). Giving a |
| client or server cert shortname will also try a lookup |
| (e.g. -sslCertInfo charlie). Use "LISTL" or "LL" |
| for a long (ls -l style) listing. |
| |
| Using "HASHON" will create subdirs [dir]/HASH and |
| [dir]/HASH with OpenSSL hash filenames (e.g. 0d5fbbf1.0) |
| symlinks pointing up to the corresponding *.crt file. |
| ([dir] is ~/.vnc/certs or one given by -ssldir.) |
| This is a useful way for other OpenSSL applications |
| (e.g. stunnel) to access all of the certs without |
| having to concatenate them. x11vnc will not use them |
| unless you specifically reference them. "HASHOFF" |
| removes these HASH subdirs. |
| |
| The LIST, LISTL, LL, ALL, HASHON, HASHOFF words can |
| also be lowercase, e.g. "list". |
| |
| -sslDelCert pem Prompts you to delete all .crt .pem .key .req files |
| associated with [pem]. x11vnc then exits. "SAVE" |
| and lookups as in -sslCertInfo apply as well. |
| |
| -sslScripts Prints out both the 'genCA' and 'genCert' x11vnc |
| openssl wrapper scripts for you to examine, modify, etc. |
| The scripts are printed to stdout and then the x11vnc |
| program exits. |
| |
| |
| -stunnel [pem] Use the stunnel(8) (stunnel.mirt.net) to provide an |
| encrypted SSL tunnel between viewers and x11vnc. |
| |
| This external tunnel method was implemented prior to the |
| integrated -ssl encryption described above. It still |
| works well and avoids the requirement of linking with |
| the OpenSSL libraries. This mode requires stunnel |
| to be installed on the system and available via PATH |
| (n.b. stunnel is often installed in sbin directories). |
| Version 4.x of stunnel is assumed (but see -stunnel3 |
| below.) |
| |
| [pem] is optional, use "-stunnel /path/to/stunnel.pem" |
| to specify a PEM certificate file to pass to stunnel. |
| See the -ssl option for more info on certificate files. |
| |
| Whether or not your stunnel has its own certificate |
| depends on your stunnel configuration; stunnel often |
| generates one at install time. See your stunnel |
| documentation for details. In any event, if you want to |
| use this certificate you must supply the full path to it |
| as [pem]. Note: the file may only be readable by root. |
| |
| [pem] may also be the special strings "TMP", "SAVE", |
| and "SAVE..." as described in the -ssl option. |
| If [pem] is not supplied, "SAVE" is assumed. |
| |
| Note that the VeNCrypt, ANONTLS, and "ANON" modes |
| are not supported in -stunnel mode. |
| |
| stunnel is started up as a child process of x11vnc and |
| any SSL connections stunnel receives are decrypted and |
| sent to x11vnc over a local socket. The strings |
| "The SSL VNC desktop is ..." and "SSLPORT=..." |
| are printed out at startup to indicate this. |
| |
| The -localhost option is enforced by default to avoid |
| people routing around the SSL channel. Use -env |
| STUNNEL_DISABLE_LOCALHOST=1 to disable this security |
| requirement. |
| |
| Set -env STUNNEL_DEBUG=1 for more debugging printout. |
| |
| Set -env STUNNEL_PROG=xxx to the full path of stunnel |
| program you want to be used (e.g. /usr/bin/stunnel4). |
| |
| Set -env STUNNEL_LISTEN=xxx to the address of the |
| network interface to listen on (the default is to listen |
| on all interfaces), e.g. STUNNEL_LISTEN=192.168.1.100. |
| |
| A simple way to add IPv6 support is STUNNEL_LISTEN=:: |
| |
| Your VNC viewer will also need to be able to connect |
| via SSL. Unfortunately not too many do this. See the |
| information about SSL viewers under the -ssl option. |
| The x11vnc project's SSVNC is an option. |
| |
| Also, in the x11vnc distribution, patched TightVNC |
| and UltraVNC Java applet jar files are provided in |
| the classes/ssl directory that do SSL connections. |
| Enable serving them with the -http, -http_ssl, or |
| -httpdir (see the option descriptions for more info.) |
| |
| Note that for the Java viewer applet usage the |
| "?PORT=xxxx" in the various URLs printed at startup |
| will need to be supplied to the web browser to connect |
| properly. |
| |
| Currently the automatic "single port" HTTPS mode of |
| -ssl is not fully supported in -stunnel mode. However, |
| it can be emulated via: |
| |
| % x11vnc -stunnel -http_ssl -http_oneport ... |
| |
| In general, it is also not too difficult to set up |
| an stunnel or other SSL tunnel on the viewer side. |
| A simple example on Unix using stunnel 3.x is: |
| |
| % stunnel -c -d localhost:5901 -r remotehost:5900 |
| % vncviewer localhost:1 |
| |
| For Windows, stunnel has been ported to it and there |
| are probably other such tools available. See the FAQ |
| and SSVNC for more examples. |
| |
| -stunnel3 [pem] Use version 3.x stunnel command line syntax instead of |
| version 4.x. The -http/-httpdir Java applet serving |
| is currently not available in this mode. |
| |
| -enc cipher:keyfile Use symmetric encryption with cipher "cipher" |
| and secret key data in "keyfile". If keyfile is |
| pw=<string> then "string" is used as the key data. |
| |
| NOTE: It is recommended that you use SSL via the -ssl |
| option instead of this option because SSL is well |
| understood and takes great care to establish unique |
| session keys and is more compatible with other software. |
| Use this option if you do not want to deal with SSL |
| certificates for authentication and do not want to |
| use SSH but want some encryption for your VNC session. |
| Or if you must interface with a symmetric key tunnel |
| that you do not have control over. |
| |
| Note that this mode will NOT work with the UltraVNC DSM |
| plugins because they alter the RFB protocol in addition |
| to tunnelling with the symmetric cipher (an unfortunate |
| choice of implementation...) |
| |
| cipher can be one of: arc4, aesv2, aes-cfb, blowfish, |
| aes256, or 3des. See the OpenSSL documentation for |
| more info. The keysize is 128 bits (except for aes256). |
| Here is one way to make a keyfile with that many bits: |
| |
| dd if=/dev/random of=./my.key bs=16 count=1 |
| |
| you will need to securely share this key with the other |
| side of the VNC connection (See SSVNC for examples). |
| |
| Example: -enc blowfish:./my.key |
| Example: -enc blowfish:pw=swordfish |
| |
| By default 16 bytes of random salt followed by 16 bytes |
| of random initialization vector are sent at the very |
| beginning of the stream. The other side must read these |
| and initialize their cipher with them. These values |
| make the session key unique (without them the security |
| is minimal). Similarly, the other side must send us |
| its random salt and IV with those same lengths. |
| |
| The salt and key data are combined to create a session |
| key using an md5 hash as described in EVP_BytesToKey(3). |
| |
| The exact call is: EVP_BytesToKey(Cipher, EVP_md5(), |
| salt, keydata, len, 1, keystr, NULL); where salt is |
| the random data as described above, and keydata is the |
| shared secret key data. keystr is the resulting session |
| key. The cipher is then seeded with keystr and uses |
| the random initialization vector as its first block. |
| |
| To modify the amount of random salt and initialization |
| vector use cipher@n,m where n is the salt length and |
| m the initialization vector length. E.g. |
| |
| -enc aes-cfb@8,16:./my.key |
| |
| It is not a good idea to set either one to zero, |
| although you may be forced to if the other side of the |
| tunnel is not under your control. |
| |
| To skip the salt and EVP_BytesToKey MD5 entirely (no |
| hashing is done: the keydata is directly inserted into |
| the cipher) specify "-1" for the salt, e.g. |
| |
| -enc blowfish@-1,16:./my.key |
| |
| The message digest can also be changed to something |
| besides the default MD5. Use cipher@md+n,m where "md" |
| can be one of sha, sha1, md5, or ripe. For example: |
| |
| -enc arc4@sha+8,16:./my.key |
| |
| The SSVNC vnc viewer project supplies a symmetric |
| encryption tool named "ultravnc_dsm_helper" that can |
| be used on the viewer side. For example: |
| |
| ssvncviewer exec='ultravnc_dsm_helper arc4 my.key 0 h:p' |
| |
| where h:p is the hostname and port of the x11vnc server. |
| ultravnc_dsm_helper may also be used standalone to |
| provide a symmetric encryption tunnel for any viewer |
| or server (VNC or otherwise.) The cipher (1st arg) |
| is basically the same syntax as we use above. |
| |
| Also see the 'Non-Ultra DSM' SSVNC option for the |
| 'UltraVNC DSM Encryption Plugin' advanced option. |
| |
| For both ways of using the viewer, you can specify the |
| salt,ivec sizes (in GUI or, e.g. arc4@8,16). |
| |
| -https [port] Use a special, separate HTTPS port (-ssl and |
| -stunnel modes only) for HTTPS Java viewer applet |
| downloading. I.e. not 5900 and not 5800 (the defaults.) |
| |
| BACKGROUND: In -ssl mode, it turns out you can use the |
| single VNC port (e.g. 5900) for both VNC and HTTPS |
| connections. (HTTPS is used to retrieve a SSL-aware |
| VncViewer.jar applet that is provided with x11vnc). |
| Since both use SSL the implementation was extended to |
| detect if HTTP traffic (i.e. GET) is taking place and |
| handle it accordingly. The URL would be, e.g.: |
| |
| https://mymachine.org:5900/ |
| |
| This is convenient for firewalls, etc, because only one |
| port needs to be allowed in. However, this heuristic |
| adds a few seconds delay to each connection and can be |
| unreliable (especially if the user takes much time to |
| ponder the Certificate dialogs in his browser, Java VM, |
| or VNC Viewer applet. That's right 3 separate "Are |
| you sure you want to connect?" dialogs!) |
| |
| END OF BACKGROUND. |
| |
| USAGE: So use the -https option to provide a separate, |
| more reliable HTTPS port that x11vnc will listen on. If |
| [port] is not provided (or is 0), one is autoselected. |
| The URL to use is printed out at startup. |
| |
| The SSL Java applet directory is specified via the |
| -httpdir option. If not supplied, -https will try |
| to guess the directory as though the -http option |
| was supplied. |
| |
| -httpsredir [port] In -ssl mode with the Java applet retrieved via HTTPS, |
| when the HTML file containing applet parameters |
| ('index.vnc' or 'proxy.vnc') is sent do NOT set the |
| applet PORT parameter to the actual VNC port but set it |
| to "port" instead. If "port" is not supplied, then |
| the port number is guessed from the Host: HTTP header. |
| |
| This is useful when an incoming TCP connection |
| redirection is performed by a router/gateway/firewall |
| from one port to an internal machine where x11vnc is |
| listening on a different port. The Java applet needs to |
| connect to the firewall/router port, not the VNC port |
| on the internal workstation. For example, one could |
| redir from mygateway.com:443 to workstation:5900. |
| |
| This spares the user from having to type in |
| https://mygateway.com/?PORT=443 into their web |
| browser. Note that port 443 is the default https port; |
| other ports must be explicitly indicated, for example: |
| https://mygateway.com:8000/?PORT=8000. To avoid having |
| to include the PORT= in the browser URL, simply supply |
| "-httpsredir" to x11vnc. |
| |
| This option does not work in -stunnel mode. |
| |
| More tricks: set the env var X11VNC_EXTRA_HTTPS_PARAMS |
| to be extra URL parameters to use. This way you do |
| not need to specify extra PARAMS in the index.vnc file. |
| E.g. x11vnc -env X11VNC_EXTRA_HTTPS_PARAMS='?GET=1' ... |
| |
| If you do not want to expose the non-SSL HTTP port to |
| the network (i.e. you just want the single VNC/HTTPS |
| port, e.g. 5900, open for connections) then specify the |
| option -env X11VNC_HTTP_LISTEN_LOCALHOST=1 This way |
| the connection to the LibVNCServer httpd server will |
| only be available on localhost (note that in -ssl mode, |
| HTTPS requests are redirected from SSL to the non-SSL |
| LibVNCServer HTTP server.) |
| |
| -http_oneport For UN-encrypted connections mode (i.e. no -ssl, |
| -stunnel, or -enc options), allow the Java VNC Viewer |
| applet to be downloaded thru the VNC port via HTTP. |
| |
| That is to say, you can use a single port for Java |
| applet viewer connections by using a URL in your web |
| browser like this, for example: |
| |
| http://hostname:5900 |
| |
| The regular, two-port mode, URL http://hostname:5800 |
| will continue to work as well. |
| |
| As mentioned above, this mode will NOT work with |
| the -ssl, -stunnel, or -enc encryption options. |
| Note that is it equivalent to '-enc none' (i.e. it |
| uses the same detection mechanism as for HTTPS, but |
| with no encryption.) |
| |
| HTTPS single-port is on by default in -ssl encrypted |
| mode (and -enc too), so you only need -http_oneport |
| when doing non-SSL encrypted connections. |
| |
| This mode could also be useful for SSH tunnels since |
| it means only one port needs to be redirected. |
| |
| The -httpsredir option may also be useful for this |
| mode when using an SSH tunnel as well as for router |
| port redirections. |
| |
| Note that the -env X11VNC_HTTP_LISTEN_LOCALHOST=1 |
| option described above under -httpsredir applies for |
| the LibVNCServer httpd server in all cases (ssl or not.) |
| |
| -ssh user@host:disp Create a remote listening port on machine "host" |
| via a SSH tunnel using the -R rport:localhost:lport |
| method. lport will be the local x11vnc listening port, |
| so a connection to rport (5900+disp) on "host" |
| will reach x11vnc. E.g. fred@snoopy.com:0 |
| |
| This could be useful if a firewall/router prevents |
| incoming connections to the x11vnc machine, but |
| the ssh machine "host" can be reached by the VNC |
| viewer. "user@" is not needed unless the remote unix |
| username differs from the current one. |
| |
| By default the remote sshd is usually configured to |
| listen only on localhost for rport, so the viewer may |
| need to ssh -L redir to "host" as well (See SSVNC to |
| automate this). The sshd setting GatewayPorts enables |
| listening on all interfaces for rport; viewers can |
| reach it more easily. |
| |
| "disp" is the VNC display for the remote SSH side, |
| e.g. 0 corresponds to port 5900, etc. If disp is |
| greater than 200 the value is used as the port. Use a |
| negative value to force a low port, e.g. host:-80 will |
| use port 80. |
| |
| If ssh-agent is not active, then the ssh password needs |
| to be entered in the terminal where x11vnc is running. |
| |
| By default the remote ssh will issue a 'sleep 300' to |
| wait for the incoming connection for 5 mins. To modify |
| this use user@host:disp+secs. |
| |
| If the remote SSH server is on a non-standard port |
| (i.e. not 22) use user@host:port:disp+secs. |
| |
| Note that the ssh process MAY NOT be killed when |
| x11vnc exits. It tries by looking at ps(1) output. |
| |
| -usepw If no other password method was supplied on the command |
| line, first look for ~/.vnc/passwd and if found use it |
| with -rfbauth; next, look for ~/.vnc/passwdfile and |
| use it with -passwdfile; otherwise, prompt the user |
| for a password to create ~/.vnc/passwd and use it with |
| the -rfbauth option. If none of these succeed x11vnc |
| exits immediately. |
| |
| -storepasswd pass file Store password "pass" as the VNC password in the |
| file "file". Once the password is stored the |
| program exits. Use the password via "-rfbauth file" |
| |
| If called with no arguments, "x11vnc -storepasswd", |
| the user is prompted for a password and it is stored |
| in the file ~/.vnc/passwd. Called with one argument, |
| that will be the file to store the prompted password in. |
| |
| -nopw Disable the big warning message when you use x11vnc |
| without some sort of password. |
| |
| -accept string Run a command (possibly to prompt the user at the |
| X11 display) to decide whether an incoming client |
| should be allowed to connect or not. "string" is |
| an external command run via system(3) or some special |
| cases described below. Be sure to quote "string" |
| if it contains spaces, shell characters, etc. If the |
| external command returns 0 the client is accepted, |
| otherwise the client is rejected. See below for an |
| extension to accept a client view-only. |
| |
| If x11vnc is running as root (say from inetd(8) or from |
| display managers xdm(1), gdm(1), etc), think about the |
| security implications carefully before supplying this |
| option (likewise for the -gone option). |
| |
| Environment: The RFB_CLIENT_IP environment variable will |
| be set to the incoming client IP number and the port |
| in RFB_CLIENT_PORT (or -1 if unavailable). Similarly, |
| RFB_SERVER_IP and RFB_SERVER_PORT (the x11vnc side |
| of the connection), are set to allow identification |
| of the tcp virtual circuit. The x11vnc process |
| id will be in RFB_X11VNC_PID, a client id number in |
| RFB_CLIENT_ID, and the number of other connected clients |
| in RFB_CLIENT_COUNT. RFB_MODE will be "accept". |
| RFB_STATE will be PROTOCOL_VERSION, SECURITY_TYPE, |
| AUTHENTICATION, INITIALISATION, NORMAL, or UNKNOWN |
| indicating up to which state the client has achieved. |
| RFB_LOGIN_VIEWONLY will be 0, 1, or -1 (unknown). |
| RFB_USERNAME, RFB_LOGIN_TIME, and RFB_CURRENT_TIME may |
| also be set. |
| |
| If "string" is "popup" then a builtin popup window |
| is used. The popup will time out after 120 seconds, |
| use "popup:N" to modify the timeout to N seconds |
| (use 0 for no timeout). |
| |
| In the case of "popup" and when the -unixpw option |
| is specified, then a *second* window will be popped |
| up after the user successfully logs in via his UNIX |
| password. This time the user will be identified as |
| UNIX:username@hostname, the "UNIX:" prefix indicates |
| which user the viewer logged as via -unixpw. The first |
| popup is only for whether to allow him to even *try* |
| to login via unix password. |
| |
| If "string" is "xmessage" then an xmessage(1) |
| invocation is used for the command. xmessage must be |
| installed on the machine for this to work. |
| |
| Both "popup" and "xmessage" will present an option |
| for accepting the client "View-Only" (the client |
| can only watch). This option will not be presented if |
| -viewonly has been specified, in which case the entire |
| display is view only. |
| |
| If the user supplied command is prefixed with something |
| like "yes:0,no:*,view:3 mycommand ..." then this |
| associates the numerical command return code with |
| the actions: accept, reject, and accept-view-only, |
| respectively. Use "*" instead of a number to indicate |
| the default action (in case the command returns an |
| unexpected value). E.g. "no:*" is a good choice. |
| |
| Note that x11vnc blocks while the external command |
| or popup is running (other clients may see no updates |
| during this period). So a person sitting a the physical |
| display is needed to respond to an popup prompt. (use |
| a 2nd x11vnc if you lock yourself out). |
| |
| More -accept tricks: use "popupmouse" to only allow |
| mouse clicks in the builtin popup to be recognized. |
| Similarly use "popupkey" to only recognize |
| keystroke responses. These are to help avoid the |
| user accidentally accepting a client by typing or |
| clicking. All 3 of the popup keywords can be followed |
| by +N+M to supply a position for the popup window. |
| The default is to center the popup window. |
| -afteraccept string As -accept, except to run a user supplied command after |
| a client has been accepted and authenticated. RFB_MODE |
| will be set to "afteraccept" and the other RFB_* |
| variables are as in -accept. Unlike -accept, the |
| command return code is not interpreted by x11vnc. |
| Example: -afteraccept 'killall xlock &' |
| -gone string As -accept, except to run a user supplied command when |
| a client goes away (disconnects). RFB_MODE will be |
| set to "gone" and the other RFB_* variables are as |
| in -accept. The "popup" actions apply as well. |
| Unlike -accept, the command return code is not |
| interpreted by x11vnc. Example: -gone 'xlock &' |
| |
| -users list If x11vnc is started as root (say from inetd(8) or from |
| display managers xdm(1), gdm(1), etc), then as soon |
| as possible after connections to the X display are |
| established try to switch to one of the users in the |
| comma separated "list". If x11vnc is not running as |
| root this option is ignored. |
| |
| Why use this option? In general it is not needed since |
| x11vnc is already connected to the X display and can |
| perform its primary functions. The option was added |
| to make some of the *external* utility commands x11vnc |
| occasionally runs work properly. In particular under |
| GNOME and KDE to implement the "-solid color" feature |
| external commands (gconftool-2 and dcop) unfortunately |
| must be run as the user owning the desktop session. |
| Since this option switches userid it also affects the |
| userid used to run the processes for the -accept and |
| -gone options. It also affects the ability to read |
| files for options such as -connect, -allow, and -remap |
| and also the ultra and tight filetransfer feature if |
| enabled. Note that the -connect file is also sometimes |
| written to. |
| |
| So be careful with this option since in some situations |
| its use can decrease security. |
| |
| In general the switch to a user will only take place |
| if the display can still be successfully opened as that |
| user (this is primarily to try to guess the actual owner |
| of the session). Example: "-users fred,wilma,betty". |
| Note that a malicious local user "barney" by |
| quickly using "xhost +" when logging in may possibly |
| get the x11vnc process to switch to user "fred". |
| What happens next? |
| |
| Under display managers it may be a long time before |
| the switch succeeds (i.e. a user logs in). To instead |
| make it switch immediately regardless if the display |
| can be reopened prefix the username with the "+" |
| character. E.g. "-users +bob" or "-users +nobody". |
| |
| The latter (i.e. switching immediately to user |
| "nobody") is the only obvious use of the -users option |
| that increases security. |
| |
| Use the following notation to associate a group with |
| a user: user1.group1,user2.group2,... Note that |
| initgroups(2) will still be called first to try to |
| switch to ALL of a user's groups (primary and additional |
| groups). Only if that fails or it is not available |
| then the single group specified as above (or the user's |
| primary group if not specified) is switched to with |
| setgid(2). Use -env X11VNC_SINGLE_GROUP=1 to prevent |
| trying initgroups(2) and only switch to the single |
| group. This sort of setting is only really needed to |
| make the ultra or tight filetransfer permissions work |
| properly. This format applies to any comma separated lis |
| t |
| of users, even the special "=" modes described below. |
| |
| In -unixpw mode, if "-users unixpw=" is supplied |
| then after a user authenticates himself via the |
| -unixpw mechanism, x11vnc will try to switch to that |
| user as though "-users +username" had been supplied. |
| If you want to limit which users this will be done for, |
| provide them as a comma separated list after "unixpw=" |
| Groups can also be specified as described above. |
| |
| Similarly, in -ssl mode, if "-users sslpeer=" is |
| supplied then after an SSL client authenticates with his |
| cert (the -sslverify option is required for this) x11vnc |
| will extract a UNIX username from the "emailAddress" |
| field (username@hostname.com) of the "Subject" of the |
| x509 SSL cert and then try to switch to that user as |
| though "-users +username" had been supplied. If you |
| want to limit which users this will be done for, provide |
| them as a comma separated list after "sslpeer=". |
| Set the env. var X11VNC_SSLPEER_CN to use the Common |
| Name (normally a hostname) instead of the Email field. |
| |
| NOTE: for sslpeer= mode the x11vnc administrator must |
| take care that any client certs he adds to -sslverify |
| have the intended UNIX username in the "emailAddress" |
| field of the cert. Otherwise a user may be able to |
| log in as another. This command can be of use in |
| checking: "openssl x509 -text -in file.crt", see the |
| "Subject:" line. Also, along with the normal RFB_* |
| env. vars. (see -accept) passed to external cmd= |
| commands, RFB_SSL_CLIENT_CERT will be set to the |
| client's x509 certificate string. |
| |
| The sslpeer= mode can aid finding X sessions via the |
| FINDDISPLAY and FINDCREATEDISPLAY mechanisms. |
| |
| To immediately switch to a user *before* connections |
| to the X display are made or any files opened use the |
| "=" character: "-users =bob". That user needs to |
| be able to open the X display and any files of course. |
| |
| The special user "guess=" means to examine the utmpx |
| database (see who(1)) looking for a user attached to |
| the display number (from DISPLAY or -display option) |
| and try him/her. To limit the list of guesses, use: |
| "-users guess=bob,betty". |
| |
| Even more sinister is the special user "lurk=" |
| that means to try to guess the DISPLAY from the utmpx |
| login database as well. So it "lurks" waiting for |
| anyone to log into an X session and then connects to it. |
| Specify a list of users after the = to limit which users |
| will be tried. To enable a different searching mode, if |
| the first user in the list is something like ":0" or |
| ":0-2" that indicates a range of DISPLAY numbers that |
| will be tried (regardless of whether they are in the |
| utmpx database) for all users that are logged in. Also |
| see the "-display WAIT:..." functionality. Examples: |
| "-users lurk=" and also "-users lurk=:0-1,bob,mary" |
| |
| Be especially careful using the "guess=" and "lurk=" |
| modes. They are not recommended for use on machines |
| with untrustworthy local users. |
| |
| -noshm Do not use the MIT-SHM extension for the polling. |
| Remote displays can be polled this way: be careful this |
| can use large amounts of network bandwidth. This is |
| also of use if the local machine has a limited number |
| of shm segments and -onetile is not sufficient. |
| -flipbyteorder Sometimes needed if remotely polled host has different |
| endianness. Ignored unless -noshm is set. |
| -onetile Do not use the new copy_tiles() framebuffer mechanism, |
| just use 1 shm tile for polling. Limits shm segments |
| used to 3. |
| |
| To disable any automatic shm reduction set the |
| env. var. X11VNC_NO_LIMIT_SHM. |
| |
| -solid [color] To improve performance, when VNC clients are connected |
| try to change the desktop background to a solid color. |
| The [color] is optional: the default color is "cyan4". |
| For a different one specify the X color (rgb.txt name, |
| e.g. "darkblue" or numerical "#RRGGBB"). |
| |
| Currently this option only works on GNOME, KDE, CDE, |
| XFCE, and classic X (i.e. with the background image |
| on the root window). The "gconftool-2", "dcop" |
| and "xfconf-query" external commands are run for |
| GNOME, KDE, and XFCE respectively. This also works |
| on native MacOSX. (There is no color selection for |
| MacOSX or XFCE.) Other desktops won't work, (send |
| us the corresponding commands if you find them). |
| If x11vnc is running as root (inetd(8) or gdm(1)), |
| the -users option may be needed for GNOME, KDE, XFCE. |
| If x11vnc guesses your desktop incorrectly, you can |
| force it by prefixing color with "gnome:", "kde:", |
| "cde:", "xfce:", or "root:". |
| |
| Update: -solid no longer works on KDE4. |
| |
| This mode works in a limited way on the Mac OS X Console |
| with one color ('kelp') using the screensaver writing |
| to the background. Look in "~/Library/Screen Savers" |
| for VncSolidColor.png to change the color. |
| |
| -blackout string Black out rectangles on the screen. "string" is a |
| comma separated list of WxH+X+Y type geometries for |
| each rectangle. If one of the items on the list is the |
| string "noptr" the mouse pointer will not be allowed |
| to go into a blacked out region. |
| -xinerama If your screen is composed of multiple monitors |
| -noxinerama glued together via XINERAMA, and that screen is |
| not a rectangle this option will try to guess the |
| areas to black out (if your system has libXinerama). |
| default: -xinerama |
| |
| In general, we have noticed on XINERAMA displays you may |
| need to use the "-xwarppointer" option if the mouse |
| pointer misbehaves and it is enabled by default. Use |
| "-noxwarppointer" if you do not want this. |
| |
| -xtrap Use the DEC-XTRAP extension for keystroke and mouse |
| input insertion. For use on legacy systems, e.g. X11R5, |
| running an incomplete or missing XTEST extension. |
| By default DEC-XTRAP will be used if XTEST server grab |
| control is missing, use -xtrap to do the keystroke and |
| mouse insertion via DEC-XTRAP as well. |
| |
| -xrandr [mode] If the display supports the XRANDR (X Resize, Rotate |
| and Reflection) extension, and you expect XRANDR events |
| to occur to the display while x11vnc is running, this |
| options indicates x11vnc should try to respond to |
| them (as opposed to simply crashing by assuming the |
| old screen size). See the xrandr(1) manpage and run |
| 'xrandr -q' for more info. [mode] is optional and |
| described below. |
| |
| Since watching for XRANDR events and trapping errors |
| increases polling overhead, only use this option if |
| XRANDR changes are expected. For example on a rotatable |
| screen PDA or laptop, or using a XRANDR-aware Desktop |
| where you resize often. It is best to be viewing with a |
| vncviewer that supports the NewFBSize encoding, since it |
| knows how to react to screen size changes. Otherwise, |
| LibVNCServer tries to do so something reasonable for |
| viewers that cannot do this (portions of the screen |
| may be clipped, unused, etc). |
| |
| Note: the default now is to check for XRANDR events, but |
| do not trap every X call that may fail due to resize. |
| If a resize event is received, the full -xrandr mode |
| is enabled. To disable even checking for events supply: |
| -noxrandr. |
| |
| "mode" defaults to "resize", which means create a |
| new, resized, framebuffer and hope all viewers can cope |
| with the change. "newfbsize" means first disconnect |
| all viewers that do not support the NewFBSize VNC |
| encoding, and then resize the framebuffer. "exit" |
| means disconnect all viewer clients, and then terminate |
| x11vnc. |
| |
| -rotate string Rotate and/or flip the framebuffer view exported by VNC. |
| This transformation is independent of XRANDR and is |
| done in software in main memory and so may be slower. |
| This mode could be useful on a handheld with portrait or |
| landscape modes that do not correspond to the scanline |
| order of the actual framebuffer. "string" can be: |
| |
| x flip along x-axis |
| y flip along y-axis |
| xy flip along x- and y-axes |
| +90 rotate 90 degrees clockwise |
| -90 rotate 90 degrees counter-clockwise |
| +90x rotate 90 degrees CW, then flip along x |
| +90y rotate 90 degrees CW, then flip along y |
| |
| these give all possible rotations and reflections. |
| |
| Aliases: same as xy: yx, +180, -180, 180 |
| same as -90: +270, 270 |
| same as +90: 90, (ditto for 90x, 90y) |
| |
| Like -scale, this transformation is applied at the very |
| end of any chain of framebuffer transformations and so |
| any options with geometries, e.g. -blackout, -clip, etc. |
| are relative to the original X (or -rawfb) framebuffer, |
| not the final one sent to VNC viewers. |
| |
| If you do not want the cursor shape to be rotated |
| prefix "string" with "nc:", e.g. "nc:+90", |
| "nc:xy", etc. |
| |
| -padgeom WxH Whenever a new vncviewer connects, the framebuffer is |
| replaced with a fake, solid black one of geometry WxH. |
| Shortly afterwards the framebuffer is replaced with the |
| real one. This is intended for use with vncviewers |
| that do not support NewFBSize and one wants to make |
| sure the initial viewer geometry will be big enough |
| to handle all subsequent resizes (e.g. under -xrandr, |
| -remote id:windowid, rescaling, etc.) |
| |
| In -unixpw mode this sets the size of the login screen. |
| Use "once:WxH" it ignore padgeom after the login |
| screen is set up. |
| |
| -o logfile Write stderr messages to file "logfile" instead of to |
| the terminal. Same as "-logfile file". To append |
| to the file use "-oa file" or "-logappend file". |
| If "logfile" contains the string "%VNCDISPLAY" |
| it is expanded to the vnc display (the name may need |
| to be guessed at.) "%HOME" works too. |
| |
| -flag file Write the "PORT=NNNN" (e.g. PORT=5900) string to |
| "file" in addition to stdout. This option could be |
| useful by wrapper script to detect when x11vnc is ready. |
| |
| -rmflag file Remove "file" at exit to signal when x11vnc is done. |
| The file is created at startup if it does not already |
| exist or if "file" is prefixed with "create:". |
| If the file is created, the x11vnc PID is placed in |
| the file. Otherwise the files contents is not changed. |
| Use prefix "nocreate:" to prevent creation. |
| |
| -rc filename Use "filename" instead of $HOME/.x11vncrc for rc file. |
| -norc Do not process any .x11vncrc file for options. |
| |
| -env VAR=VALUE Set the environment variable 'VAR' to value 'VALUE' |
| at x11vnc startup. This is a convenience utility to |
| avoid shell script wrappers, etc. to set the env. var. |
| You may specify as many of these as needed on the |
| command line. |
| -prog /path/to/x11vnc Set the full path to the x11vnc program for cases when |
| it cannot be determined from argv[0] (e.g. tcpd/inetd) |
| |
| -h, -help Print this help text. |
| -?, -opts Only list the x11vnc options. |
| -V, -version Print program version and last modification date. |
| -license Print out license information. Same as -copying and |
| -warranty. |
| |
| -dbg Instead of exiting after cleaning up, run a simple |
| "debug crash shell" when fatal errors are trapped. |
| |
| -q, -quiet Be quiet by printing less informational output to |
| stderr. (use -noquiet to undo an earlier -quiet.) |
| |
| The -quiet option does not eliminate all informational |
| output, it only reduces it. It is ignored in most |
| auxiliary usage modes, e.g. -storepasswd. To eliminate |
| all output use: 2>/dev/null 1>&2, etc. |
| |
| -v, -verbose Print out more information to stderr. |
| |
| -bg Go into the background after screen setup. Messages to |
| stderr are lost unless -o logfile is used. Something |
| like this could be useful in a script: |
| port=`ssh -t $host "x11vnc -display :0 -bg" | grep PORT |
| ` |
| port=`echo "$port" | sed -e 's/PORT=//'` |
| port=`expr $port - 5900` |
| vncviewer $host:$port |
| |
| -modtweak Option -modtweak automatically tries to adjust the AltGr |
| -nomodtweak and Shift modifiers for differing language keyboards |
| between client and host. Otherwise, only a single key |
| press/release of a Keycode is simulated (i.e. ignoring |
| the state of the modifiers: this usually works for |
| identical keyboards). Also useful in resolving cases |
| where a Keysym is bound to multiple keys (e.g. "<" + ">" |
| and "," + "<" keys). Default: -modtweak |
| |
| If you are having trouble with with keys and -xkb or |
| -noxkb, and similar things don't help, try -nomodtweak. |
| |
| On some HP-UX systems it is been noted that they have |
| an odd keymapping where a single keycode will have a |
| keysym, e.g. "#", up to three times. You can check |
| via "xmodmap -pk" or the -dk option. The failure |
| is when you try to type "#" it yields "3". If you |
| see this problem try setting the environment variable |
| MODTWEAK_LOWEST=1 to see if it helps. |
| |
| -xkb When in modtweak mode, use the XKEYBOARD extension (if |
| -noxkb the X display supports it) to do the modifier tweaking. |
| This is powerful and should be tried if there are still |
| keymapping problems when using -modtweak by itself. |
| The default is to check whether some common keysyms, |
| e.g. !, @, [, are only accessible via -xkb mode and if |
| so then automatically enable the mode. To disable this |
| automatic detection use -noxkb. |
| |
| When -xkb mode is active you can set these env. vars. |
| They apply only when there is ambiguity as to which |
| key to choose (i.e the mapping is not one-to-one). |
| NOKEYHINTS=1: for up ascii keystrokes do not use score |
| hints saved when the key was pressed down. NOANYDOWN=1: |
| for up keystrokes do not resort to searching through |
| keys that are currently pressed down. KEYSDOWN=N: |
| remember the last N keys press down for tie-breaking |
| when an up keystroke comes in. |
| |
| -capslock When in -modtweak (the default) or -xkb mode, |
| if a keysym in the range A-Z comes in check the X |
| server to see if the Caps_Lock is set. If it is do |
| not artificially press Shift to generate the keysym. |
| This will enable the CapsLock key to behave correctly |
| in some circumstances: namely *both* the VNC viewer |
| machine and the x11vnc X server are in the CapsLock |
| on state. If one side has CapsLock on and the other |
| off and the keyboard is not behaving as you think it |
| should you should correct the CapsLock states (hint: |
| pressing CapsLock inside and outside of the viewer can |
| help toggle them both to the correct state). However, |
| for best results do not use this option, but rather |
| *only* enable CapsLock on the VNC viewer side (i.e. by |
| pressing CapsLock outside of the viewer window, also |
| -skip_lockkeys below). Also try -nomodtweak for a |
| possible workaround. |
| |
| -skip_lockkeys Have x11vnc ignore all Caps_Lock, Shift_Lock, Num_Lock, |
| -noskip_lockkeys Scroll_Lock keysyms received from viewers. The idea is |
| you press Caps_Lock on the VNC Viewer side but that does |
| not change the lock state in the x11vnc-side X server. |
| Nevertheless your capitalized letters come in over |
| the wire and are applied correctly to the x11vnc-side |
| X server. Note this mode probably won't do what you |
| want in -nomodtweak mode. Also, a kludge for KP_n |
| digits is always done in this mode: they are mapped to |
| regular digit keysyms. See also -capslock above. |
| The default is -noskip_lockkeys. |
| |
| -skip_keycodes string Ignore the comma separated list of decimal keycodes. |
| Perhaps these are keycodes not on your keyboard but |
| your X server thinks exist. Currently only applies |
| to -xkb mode. Use this option to help x11vnc in the |
| reverse problem it tries to solve: Keysym -> Keycode(s) |
| when ambiguities exist (more than one Keycode per |
| Keysym). Run 'xmodmap -pk' to see your keymapping. |
| Example: "-skip_keycodes 94,114" |
| -sloppy_keys Experimental option that tries to correct some |
| "sloppy" key behavior. E.g. if at the viewer you |
| press Shift+Key but then release the Shift before |
| Key that could give rise to extra unwanted characters |
| (usually only between keyboards of different languages). |
| Only use this option if you observe problems with |
| some keystrokes. |
| -skip_dups Some VNC viewers send impossible repeated key events, |
| -noskip_dups e.g. key-down, key-down, key-up, key-up all for the same |
| key, or 20 downs in a row for the same modifier key! |
| Setting -skip_dups means to skip these duplicates and |
| just process the first event. Note: some VNC viewers |
| assume they can send down's without the corresponding |
| up's and so you should not set this option for |
| these viewers (symptom: some keys do not autorepeat) |
| Default: -noskip_dups |
| -add_keysyms If a Keysym is received from a VNC viewer and that |
| -noadd_keysyms Keysym does not exist in the X server, then add the |
| Keysym to the X server's keyboard mapping on an unused |
| key. Added Keysyms will be removed periodically and |
| also when x11vnc exits. Default: -add_keysyms |
| -clear_mods At startup and exit clear the modifier keys by sending |
| KeyRelease for each one. The Lock modifiers are skipped. |
| Used to clear the state if the display was accidentally |
| left with any pressed down. |
| -clear_keys As -clear_mods, except try to release ANY pressed key. |
| Note that this option and -clear_mods can interfere |
| with a person typing at the physical keyboard. |
| -clear_all As -clear_keys, except try to release any CapsLock, |
| NumLock, etc. locks as well. |
| |
| -remap string Read Keysym remappings from file named "string". |
| Format is one pair of Keysyms per line (can be name |
| or hex value) separated by a space. If no file named |
| "string" exists, it is instead interpreted as this |
| form: key1-key2,key3-key4,... See <X11/keysymdef.h> |
| header file for a list of Keysym names, or use xev(1). |
| |
| To map a key to a button click, use the fake Keysyms |
| "Button1", ..., etc. E.g: "-remap Super_R-Button2" |
| (useful for pasting on a laptop) |
| |
| I use these if the machine I am viewing from does not |
| have a scrollwheel or I don't like using the one it has: |
| |
| -remap Super_R-Button4,Menu-Button5 |
| -remap KP_Add-Button4,KP_Enter-Button5 |
| |
| the former would be used on a PC, the latter on a |
| MacBook. This way those little used keys can be used |
| to generate bigger hops than the Up and Down arrows |
| provide. One can scroll through text or web pages more |
| quickly this way (especially if x11vnc scroll detection |
| is active.) |
| |
| Use Button44, Button12, etc. for multiple clicks. |
| |
| To disable a keysym (i.e. make it so it will not be |
| injected), remap it to "NoSymbol" or "None". |
| |
| Dead keys: "dead" (or silent, mute) keys are keys that |
| do not produce a character but must be followed by a 2nd |
| keystroke. This is often used for accenting characters, |
| e.g. to put "`" on top of "a" by pressing the dead |
| key and then "a". Note that this interpretation |
| is not part of core X11, it is up to the toolkit or |
| application to decide how to react to the sequence. |
| The X11 names for these keysyms are "dead_grave", |
| "dead_acute", etc. However some VNC viewers send the |
| keysyms "grave", "acute" instead thereby disabling |
| the accenting. To work around this -remap can be used. |
| For example "-remap grave-dead_grave,acute-dead_acute" |
| As a convenience, "-remap DEAD" applies these remaps: |
| |
| g grave-dead_grave |
| a acute-dead_acute |
| c asciicircum-dead_circumflex |
| t asciitilde-dead_tilde |
| m macron-dead_macron |
| b breve-dead_breve |
| D abovedot-dead_abovedot |
| d diaeresis-dead_diaeresis |
| o degree-dead_abovering |
| A doubleacute-dead_doubleacute |
| r caron-dead_caron |
| e cedilla-dead_cedilla |
| |
| If you just want a subset use the first letter |
| label, e.g. "-remap DEAD=ga" to get the first two. |
| Additional remaps may also be supplied via commas, |
| e.g. "-remap DEAD=ga,Super_R-Button2". Finally, |
| "DEAD=missing" means to apply all of the above as |
| long as the left hand member is not already in the |
| X11 keymap. |
| |
| -norepeat Option -norepeat disables X server key auto repeat when |
| -repeat VNC clients are connected and VNC keyboard input is |
| not idle for more than 5 minutes. This works around a |
| repeating keystrokes bug (triggered by long processing |
| delays between key down and key up client events: |
| either from large screen changes or high latency). |
| Default: -norepeat |
| |
| You can set the env. var. X11VNC_IDLE_TIMEOUT to the |
| number of idle seconds you want (5min = 300secs). |
| |
| Note: your VNC viewer side will likely do autorepeating, |
| so this is no loss unless someone is simultaneously at |
| the real X display. |
| |
| Use "-norepeat N" to set how many times norepeat will |
| be reset if something else (e.g. X session manager) |
| undoes it. The default is 2. Use a negative value |
| for unlimited resets. |
| |
| -nofb Ignore video framebuffer: only process keyboard and |
| pointer. Intended for use with Win2VNC and x2vnc |
| dual-monitor setups. |
| -nobell Do not watch for XBell events. (no beeps will be heard) |
| Note: XBell monitoring requires the XKEYBOARD extension. |
| -nosel Do not manage exchange of X selection/cutbuffer between |
| VNC viewers and the X server at all. |
| -noprimary Do not poll the PRIMARY selection for changes to send |
| back to clients. (PRIMARY is still set on received |
| changes, however). |
| -nosetprimary Do not set the PRIMARY selection for changes received |
| from VNC clients. |
| -noclipboard Do not poll the CLIPBOARD selection for changes to send |
| back to clients. (CLIPBOARD is still set on received |
| changes, however). |
| -nosetclipboard Do not set the CLIPBOARD selection for changes |
| received from VNC clients. |
| -seldir string If direction string is "send", only send the selection |
| to viewers, and if it is "recv" only receive it from |
| viewers. To work around apps setting the selection |
| too frequently and messing up the other end. You can |
| actually supply a comma separated list of directions, |
| including "debug" to turn on debugging output. |
| |
| -cursor [mode] Sets how the pointer cursor shape (little icon at the |
| -nocursor mouse pointer) should be handled. The "mode" string |
| is optional and is described below. The default |
| is to show some sort of cursor shape(s). How this |
| is done depends on the VNC viewer and the X server. |
| Use -nocursor to disable cursor shapes completely. |
| |
| Some VNC viewers support the TightVNC CursorPosUpdates |
| and CursorShapeUpdates extensions (cuts down on |
| network traffic by not having to send the cursor image |
| every time the pointer is moved), in which case these |
| extensions are used (see -nocursorshape and -nocursorpos |
| below to disable). For other viewers the cursor shape |
| is written directly to the framebuffer every time the |
| pointer is moved or changed and gets sent along with |
| the other framebuffer updates. In this case, there |
| will be some lag between the vnc viewer pointer and |
| the remote cursor position. |
| |
| If the X display supports retrieving the cursor shape |
| information from the X server, then the default is |
| to use that mode. On Solaris this can be done with |
| the SUN_OVL extension using -overlay (see also the |
| -overlay_nocursor option). A similar overlay scheme |
| is used on IRIX. Xorg (e.g. Linux) and recent Solaris |
| Xsun servers support the XFIXES extension to retrieve |
| the exact cursor shape from the X server. If XFIXES |
| is present it is preferred over Overlay and is used by |
| default (see -noxfixes below). This can be disabled |
| with -nocursor, and also some values of the "mode" |
| option below. |
| |
| Note that under XFIXES cursors with transparency (alpha |
| channel) will usually not be exactly represented and one |
| may find Overlay preferable. See also the -alphacut |
| and -alphafrac options below as fudge factors to try |
| to improve the situation for cursors with transparency |
| for a given theme. |
| |
| The "mode" string can be used to fine-tune the |
| displaying of cursor shapes. It can be used the |
| following ways: |
| |
| "-cursor arrow" - just show the standard arrow |
| nothing more or nothing less. |
| |
| "-cursor none" - same as "-nocursor" |
| |
| "-cursor X" - when the cursor appears to be on the |
| root window, draw the familiar X shape. Some desktops |
| such as GNOME cover up the root window completely, |
| and so this will not work, try "X1", etc, to try to |
| shift the tree depth. On high latency links or slow |
| machines there will be a time lag between expected and |
| the actual cursor shape. |
| |
| "-cursor some" - like "X" but use additional |
| heuristics to try to guess if the window should have |
| a windowmanager-like resizer cursor or a text input |
| I-beam cursor. This is a complete hack, but may be |
| useful in some situations because it provides a little |
| more feedback about the cursor shape. |
| |
| "-cursor most" - try to show as many cursors as |
| possible. Often this will only be the same as "some" |
| unless the display has overlay visuals or XFIXES |
| extensions available. On Solaris and IRIX if XFIXES |
| is not available, -overlay mode will be attempted. |
| |
| -cursor_drag Show cursor shape changes even when the mouse is being |
| dragged with a mouse button down. This is useful if you |
| want to be able to see Drag-and-Drop cursor icons, etc. |
| |
| -arrow n Choose an alternate "arrow" cursor from a set of |
| some common ones. n can be 1 to 6. Default is: 1 |
| Ignored when in XFIXES cursor-grabbing mode. |
| |
| -noxfixes Do not use the XFIXES extension to draw the exact cursor |
| shape even if it is available. |
| |
| Note: To work around a crash in Xorg 1.5 and later |
| some people needed to use -noxfixes. The Xorg crash |
| occurred right after a Display Manager (e.g. GDM) login. |
| Starting with x11vnc 0.9.9 it tries to automatically |
| avoid using XFIXES until it is sure a window manager |
| is running. See the -reopen option for more info and |
| how to use X11VNC_AVOID_WINDOWS=never to disable it. |
| |
| -alphacut n When using the XFIXES extension for the cursor shape, |
| cursors with transparency will not usually be displayed |
| exactly (but opaque ones will). This option sets n as |
| a cutoff for cursors that have transparency ("alpha |
| channel" with values ranging from 0 to 255) Any cursor |
| pixel with alpha value less than n becomes completely |
| transparent. Otherwise the pixel is completely opaque. |
| Default 240 |
| |
| -alphafrac fraction With the threshold in -alphacut some cursors will become |
| almost completely transparent because their alpha values |
| are not high enough. For those cursors adjust the |
| alpha threshold until fraction of the non-zero alpha |
| channel pixels become opaque. Default 0.33 |
| -alpharemove By default, XFIXES cursors pixels with transparency have |
| the alpha factor multiplied into the RGB color values |
| (i.e. that corresponding to blending the cursor with a |
| black background). Specify this option to remove the |
| alpha factor. (useful for light colored semi-transparent |
| cursors). |
| -noalphablend In XFIXES mode do not send cursor alpha channel data |
| to LibVNCServer. The default is to send it. The |
| alphablend effect will only be visible in -nocursorshape |
| mode or for clients with cursorshapeupdates turned |
| off. (However there is a hack for 32bpp with depth 24, |
| it uses the extra 8 bits to store cursor transparency |
| for use with a hacked vncviewer that applies the |
| transparency locally. See the FAQ for more info). |
| |
| -nocursorshape Do not use the TightVNC CursorShapeUpdates extension |
| even if clients support it. See -cursor above. |
| -cursorpos Option -cursorpos enables sending the X cursor position |
| -nocursorpos back to all vnc clients that support the TightVNC |
| CursorPosUpdates extension. Other clients will be able |
| to see the pointer motions. Default: -cursorpos |
| -xwarppointer Move the pointer with XWarpPointer(3X) instead of |
| -noxwarppointer the XTEST extension. Use this as a workaround |
| if the pointer motion behaves incorrectly, e.g. |
| on touchscreens or other non-standard setups. |
| |
| It is also sometimes needed on XINERAMA displays and is |
| enabled by default if XINERAMA is found to be active. |
| To prevent this, use -noxwarppointer. |
| |
| -always_inject Even if there is no displacement (dx = dy = 0) for a |
| VNC mouse event force the pointer to the indicated x,y |
| position anyway. Recent (2009) gui toolkits (gnome) |
| have problems with x11vnc's original mouse input |
| injection method. So x11vnc's mouse input injection |
| method has been modified. To regain the OLD behavior |
| use this option: -always_inject. Then x11vnc will |
| always force positioning the mouse to the x,y position |
| even if that position has not changed since the previous |
| VNC input event. |
| |
| The first place this problem was noticed was in gnome |
| terminal: if you pressed and released mouse button 3, a |
| menu was posted and then its first element 'New Terminal |
| Window' was activated. This was because x11vnc injected |
| the mouse position twice: once on ButtonPress and again |
| on ButtonRelease. The toolkit interpreted the 2nd one |
| as mouse motion even though the mouse hadn't moved. |
| So now by default x11vnc tries to avoid injecting the |
| 2nd one. |
| |
| Note that with the new default x11vnc will be oblivious |
| to applications moving the pointer (warping) or the |
| user at the physical display moving it. So it might, |
| e.g., inject ButtonRelease at the wrong position. |
| If this (or similar scenarios) causes problems in your |
| environment, specify -always_inject for the old method. |
| |
| -buttonmap string String to remap mouse buttons. Format: IJK-LMN, this |
| maps buttons I -> L, etc., e.g. -buttonmap 13-31 |
| |
| Button presses can also be mapped to keystrokes: replace |
| a button digit on the right of the dash with :<sym>: |
| or :<sym1>+<sym2>: etc. for multiple keys. For example, |
| if the viewing machine has a mouse-wheel (buttons 4 5) |
| but the x11vnc side does not, these will do scrolls: |
| -buttonmap 12345-123:Prior::Next: |
| -buttonmap 12345-123:Up+Up+Up::Down+Down+Down: |
| |
| See <X11/keysymdef.h> header file for a list of Keysyms, |
| or use the xev(1) program. Note: mapping of button |
| clicks to Keysyms may not work if -modtweak or -xkb is |
| needed for the Keysym. |
| |
| If you include a modifier like "Shift_L" the |
| modifier's up/down state is toggled, e.g. to send |
| "The" use :Shift_L+t+Shift_L+h+e: (the 1st one is |
| shift down and the 2nd one is shift up). (note: the |
| initial state of the modifier is ignored and not reset) |
| To include button events use "Button1", ... etc. |
| |
| -buttonmap currently does not work on MacOSX console |
| or in -rawfb mode. |
| |
| Workaround: use -buttonmap IJ...-LM...=n to limit the |
| number of mouse buttons to n, e.g. 123-123=3. This will |
| prevent x11vnc from crashing if the X server reports |
| there are 5 buttons (4/5 scroll wheel), but there are |
| only really 3. |
| |
| -nodragging Do not update the display during mouse dragging events |
| (mouse button held down). Greatly improves response on |
| slow setups, but you lose all visual feedback for drags, |
| text selection, and some menu traversals. It overrides |
| any -pointer_mode setting. |
| |
| -ncache n Client-side caching scheme. Framebuffer memory "n" |
| (an integer) times that of the full display is allocated |
| below the actual framebuffer to cache screen contents |
| for rapid retrieval. So a W x H frambuffer is expanded |
| to a W x (n+1)*H one. Use 0 to disable. |
| |
| The "n" is actually optional, the default is 10. |
| |
| For this and the other -ncache* options below you can |
| abbreviate "-ncache" with "-nc". Also, "-nonc" |
| is the same as "-ncache 0" |
| |
| This is an experimental option, currently implemented in |
| an awkward way in that in the VNC Viewer you can see the |
| pixel cache contents if you scroll down, etc. So you |
| will have to set things up so you can't see that region. |
| If this method is successful, the changes required for |
| clients to do this less awkwardly will be investigated. |
| |
| The SSVNC viewer does a good job at automatically hiding |
| the pixel cache region. Or use SSVNC's -ycrop option |
| to explicitly hide the region. |
| |
| Note that this mode consumes a huge amount of memory, |
| both on the x11vnc server side and on the VNC Viewer |
| side. If n=2 then the amount of RAM used is roughly |
| tripled for both x11vnc and the VNC Viewer. As a rule |
| of thumb, note that 1280x1024 at depth 24 is about 5MB |
| of pixel data. |
| |
| For reasonable response when cycling through 4 to 6 |
| large (e.g. web browser) windows a value n of 6 to 12 |
| is recommended. (that's right: ~10X more memory...) |
| |
| Because of the way window backingstore and saveunders |
| are implemented, n must be even. It will be incremented |
| by 1 if it is not. |
| |
| This mode also works for native MacOS X, but may not |
| be as effective as the X version. This is due to a |
| number of things, one is the drop-shadow compositing |
| that leaves extra areas that need to be repaired (see |
| -ncache_pad). Another is the window iconification |
| animations need to be avoided (see -macicontime). |
| It appears the that the 'Scale' animation mode gives |
| better results than the 'Genie' one. Also, window event |
| detection not as accurate as the X version. |
| |
| -ncache_cr In -ncache mode, try to do copyrect opaque window |
| moves/drags instead of wireframes (this can induce |
| painting errors). The wireframe will still be used when |
| moving a window whose save-unders has not yet been set |
| or has been invalidated. |
| |
| Some VNC Viewers provide better response than others |
| with this option. On Unix, realvnc viewer gives |
| smoother drags than tightvnc viewer. Response may also |
| be choppy if the server side machine is too slow. |
| |
| Sometimes on very slow modem connections, this actually |
| gives an improvement because no pixel data at all |
| (not even the box animation) is sent during the drag. |
| |
| -ncache_no_moveraise In -ncache mode, do not assume that moving a window |
| will cause the window manager to raise it to the top |
| of the stack. The default is to assume it does, and |
| so at the beginning of any wireframe, etc, window moves |
| the window will be pushed to top in the VNC viewer. |
| |
| -ncache_no_dtchange In -ncache mode, do not try to guess when the desktop |
| (viewport) changes to another one (i.e. another |
| workarea). The default is to try to guess and when |
| detected try to make the transistion more smoothly. |
| |
| -ncache_no_rootpixmap In -ncache mode, do not try to snapshot the desktop |
| background to use in guessing or reconstructing window |
| save-unders. |
| |
| -ncache_keep_anims In -ncache mode, do not try to disable window |
| manager animations and other effects (that usually |
| degrade ncache performance or cause painting errors). |
| The default is to try to disable them on KDE (but not |
| GNOME) when VNC clients are connected. |
| |
| For other window managers or desktops that provide |
| animations, effects, compositing, translucency, |
| etc. that interfere with the -ncache method you will |
| have to disable them manually. |
| |
| -ncache_old_wm In -ncache mode, enable some heuristics for old style |
| window managers such as fvwm and twm. |
| |
| -ncache_pad n In -ncache mode, pad each window with n pixels for the |
| caching rectangles. This can be used to try to improve |
| the situation with dropshadows or other compositing |
| (e.g. MacOS X window manager), although it could make |
| things worse. The default is 0 on Unix and 24 on |
| MacOS X. |
| -debug_ncache Turn on debugging and profiling output under -ncache. |
| |
| -wireframe [str] Try to detect window moves or resizes when a mouse |
| -nowireframe button is held down and show a wireframe instead of |
| the full opaque window. This is based completely on |
| heuristics and may not always work: it depends on your |
| window manager and even how you move things around. |
| See -pointer_mode below for discussion of the "bogging |
| down" problem this tries to avoid. |
| Default: -wireframe |
| |
| Shorter aliases: -wf [str] and -nowf |
| |
| The value "str" is optional and, of course, is |
| packed with many tunable parameters for this scheme: |
| |
| Format: shade,linewidth,percent,T+B+L+R,mod,t1+t2+t3+t4 |
| Default: 0xff,2,0,32+8+8+8,all,0.15+0.30+5.0+0.125 |
| |
| If you leave nothing between commas: ",," the default |
| value is used. If you don't specify enough commas, |
| the trailing parameters are set to their defaults. |
| |
| "shade" indicate the "color" for the wireframe, |
| usually a greyscale: 0-255, however for 16 and 32bpp you |
| can specify an rgb.txt X color (e.g. "dodgerblue") or |
| a value > 255 is treated as RGB (e.g. red is 0xff0000). |
| "linewidth" sets the width of the wireframe in pixels. |
| "percent" indicates to not apply the wireframe scheme |
| to windows with area less than this percent of the |
| full screen. |
| |
| "T+B+L+R" indicates four integers for how close in |
| pixels the pointer has to be from the Top, Bottom, Left, |
| or Right edges of the window to consider wireframing. |
| This is a speedup to quickly exclude a window from being |
| wireframed: set them all to zero to not try the speedup |
| (scrolling and selecting text will likely be slower). |
| |
| "mod" specifies if a button down event in the |
| interior of the window with a modifier key (Alt, Shift, |
| etc.) down should indicate a wireframe opportunity. |
| It can be "0" or "none" to skip it, "1" or "all" |
| to apply it to any modifier, or "Shift", "Alt", |
| "Control", "Meta", "Super", or "Hyper" to only |
| apply for that type of modifier key. |
| |
| "t1+t2+t3+t4" specify four floating point times in |
| seconds: t1 is how long to wait for the pointer to move, |
| t2 is how long to wait for the window to start moving |
| or being resized (for some window managers this can be |
| rather long), t3 is how long to keep a wireframe moving |
| before repainting the window. t4 is the minimum time |
| between sending wireframe "animations". If a slow |
| link is detected, these values may be automatically |
| changed to something better for a slow link. |
| |
| -nowireframelocal By default, mouse motion and button presses of a |
| user sitting at the LOCAL display are monitored for |
| wireframing opportunities (so that the changes will be |
| sent efficiently to the VNC clients). Use this option |
| to disable this behavior. |
| |
| -wirecopyrect mode Since the -wireframe mechanism evidently tracks moving |
| -nowirecopyrect windows accurately, a speedup can be obtained by |
| telling the VNC viewers to locally copy the translated |
| window region. This is the VNC CopyRect encoding: |
| the framebuffer update doesn't need to send the actual |
| new image data. |
| |
| Shorter aliases: -wcr [mode] and -nowcr |
| |
| "mode" can be "never" (same as -nowirecopyrect) |
| to never try the copyrect, "top" means only do it if |
| the window was not covered by any other windows, and |
| "always" means to translate the orginally unobscured |
| region (this may look odd as the remaining pieces come |
| in, but helps on a slow link). Default: "always" |
| |
| Note: there can be painting errors or slow response |
| when using -scale so you may want to disable CopyRect |
| in this case "-wirecopyrect never" on the command |
| line or by remote-control. Or you can also use the |
| "-scale xxx:nocr" scale option. |
| |
| -debug_wireframe Turn on debugging info printout for the wireframe |
| heuristics. "-dwf" is an alias. Specify multiple |
| times for more output. |
| |
| -scrollcopyrect mode Like -wirecopyrect, but use heuristics to try to guess |
| -noscrollcopyrect if a window has scrolled its contents (either vertically |
| or horizontally). This requires the RECORD X extension |
| to "snoop" on X applications (currently for certain |
| XCopyArea and XConfigureWindow X protocol requests). |
| Examples: Hitting <Return> in a terminal window when the |
| cursor was at the bottom, the text scrolls up one line. |
| Hitting <Down> arrow in a web browser window, the web |
| page scrolls up a small amount. Or scrolling with a |
| scrollbar or mouse wheel. |
| |
| Shorter aliases: -scr [mode] and -noscr |
| |
| This scheme will not always detect scrolls, but when |
| it does there is a nice speedup from using the VNC |
| CopyRect encoding (see -wirecopyrect). The speedup |
| is both in reduced network traffic and reduced X |
| framebuffer polling/copying. On the other hand, it may |
| induce undesired transients (e.g. a terminal cursor |
| being scrolled up when it should not be) or other |
| painting errors (window tearing, bunching-up, etc). |
| These are automatically repaired in a short period |
| of time. If this is unacceptable disable the feature |
| with -noscrollcopyrect. |
| |
| Screen clearing kludges: for testing at least, there |
| are some "magic key sequences" (must be done in less |
| than 1 second) to aid repairing painting errors that |
| may be seen when using this mode: |
| |
| 3 Alt_L's in a row: resend whole screen, |
| 4 Alt_L's in a row: reread and resend whole screen, |
| 3 Super_L's in a row: mark whole screen for polling, |
| 4 Super_L's in a row: reset RECORD context, |
| 5 Super_L's in a row: try to push a black screen |
| |
| note: Alt_L is the Left "Alt" key (a single key) |
| Super_L is the Left "Super" key (Windows flag). |
| Both of these are modifier keys, and so should not |
| generate characters when pressed by themselves. Also, |
| your VNC viewer may have its own refresh hot-key |
| or button. |
| |
| "mode" can be "never" (same as -noscrollcopyrect) |
| to never try the copyrect, "keys" means to try it |
| in response to keystrokes only, "mouse" means to |
| try it in response to mouse events only, "always" |
| means to do both. Default: "always" |
| |
| Note: there can be painting errors or slow response |
| when using -scale so you may want to disable CopyRect |
| in this case "-scrollcopyrect never" on the command |
| line or by remote-control. Or you can also use the |
| "-scale xxx:nocr" scale option. |
| |
| -scr_area n Set the minimum area in pixels for a rectangle |
| to be considered for the -scrollcopyrect detection |
| scheme. This is to avoid wasting the effort on small |
| rectangles that would be quickly updated the normal way. |
| E.g. suppose an app updated the position of its skinny |
| scrollbar first and then shifted the large panel |
| it controlled. We want to be sure to skip the small |
| scrollbar and get the large panel. Default: 60000 |
| |
| -scr_skip list Skip scroll detection for applications matching |
| the comma separated list of strings in "list". |
| Some applications implement their scrolling in |
| strange ways where the XCopyArea, etc, also applies |
| to invisible portions of the window: if we CopyRect |
| those areas it looks awful during the scroll and |
| there may be painting errors left after the scroll. |
| Soffice.bin is the worst known offender. |
| |
| Use "##" to denote the start of the application class |
| (e.g. "##XTerm") and "++" to denote the start |
| of the application instance name (e.g. "++xterm"). |
| The string your list is matched against is of the form |
| "^^WM_NAME##Class++Instance<same-for-any-subwindows>" |
| The "xlsclients -la" command will provide this info. |
| |
| If a pattern is prefixed with "KEY:" it only applies |
| to Keystroke generated scrolls (e.g. Up arrow). If it |
| is prefixed with "MOUSE:" it only applies to Mouse |
| induced scrolls (e.g. dragging on a scrollbar). |
| Default: ##Soffice.bin,##StarOffice,##OpenOffice |
| |
| -scr_inc list Opposite of -scr_skip: this list is consulted first |
| and if there is a match the window will be monitored |
| via RECORD for scrolls irrespective of -scr_skip. |
| Use -scr_skip '*' to skip anything that does not match |
| your -scr_inc. Use -scr_inc '*' to include everything. |
| |
| -scr_keys list For keystroke scroll detection, only apply the RECORD |
| heuristics to the comma separated list of keysyms in |
| "list". You may find the RECORD overhead for every |
| one of your keystrokes disrupts typing too much, but you |
| don't want to turn it off completely with "-scr mouse" |
| and -scr_parms does not work or is too confusing. |
| |
| The listed keysyms can be numeric or the keysym |
| names in the <X11/keysymdef.h> header file or from the |
| xev(1) program. Example: "-scr_keys Up,Down,Return". |
| One probably wants to have application specific lists |
| (e.g. for terminals, etc) but that is too icky to think |
| about for now... |
| |
| If "list" begins with the "-" character the list |
| is taken as an exclude list: all keysyms except those |
| list will be considered. The special string "builtin" |
| expands to an internal list of keysyms that are likely |
| to cause scrolls. BTW, by default modifier keys, |
| Shift_L, Control_R, etc, are skipped since they almost |
| never induce scrolling by themselves. |
| |
| -scr_term list Yet another cosmetic kludge. Apply shell/terminal |
| heuristics to applications matching comma separated |
| list (same as for -scr_skip/-scr_inc). For example an |
| annoying transient under scroll detection is if you |
| hit Enter in a terminal shell with full text window, |
| the solid text cursor block will be scrolled up. |
| So for a short time there are two (or more) block |
| cursors on the screen. There are similar scenarios, |
| (e.g. an output line is duplicated). |
| |
| These transients are induced by the approximation of |
| scroll detection (e.g. it detects the scroll, but not |
| the fact that the block cursor was cleared just before |
| the scroll). In nearly all cases these transient errors |
| are repaired when the true X framebuffer is consulted |
| by the normal polling. But they are distracting, so |
| what this option provides is extra "padding" near the |
| bottom of the terminal window: a few extra lines near |
| the bottom will not be scrolled, but rather updated |
| from the actual X framebuffer. This usually reduces |
| the annoying artifacts. Use "none" to disable. |
| Default: "term" |
| |
| -scr_keyrepeat lo-hi If a key is held down (or otherwise repeats rapidly) and |
| this induces a rapid sequence of scrolls (e.g. holding |
| down an Arrow key) the "scrollcopyrect" detection |
| and overhead may not be able to keep up. A time per |
| single scroll estimate is performed and if that estimate |
| predicts a sustainable scrollrate of keys per second |
| between "lo" and "hi" then repeated keys will be |
| DISCARDED to maintain the scrollrate. For example your |
| key autorepeat may be 25 keys/sec, but for a large |
| window or slow link only 8 scrolls per second can be |
| sustained, then roughly 2 out of every 3 repeated keys |
| will be discarded during this period. Default: "4-20" |
| |
| -scr_parms string Set various parameters for the scrollcopyrect mode. |
| The format is similar to that for -wireframe and packed |
| with lots of parameters: |
| |
| Format: T+B+L+R,t1+t2+t3,s1+s2+s3+s4+s5 |
| Default: 0+64+32+32,0.02+0.10+0.9,0.03+0.06+0.5+0.1+5.0 |
| |
| If you leave nothing between commas: ",," the default |
| value is used. If you don't specify enough commas, |
| the trailing parameters are set to their defaults. |
| |
| "T+B+L+R" indicates four integers for how close in |
| pixels the pointer has to be from the Top, Bottom, Left, |
| or Right edges of the window to consider scrollcopyrect. |
| If -wireframe overlaps it takes precedence. This is a |
| speedup to quickly exclude a window from being watched |
| for scrollcopyrect: set them all to zero to not try |
| the speedup (things like selecting text will likely |
| be slower). |
| |
| "t1+t2+t3" specify three floating point times in |
| seconds that apply to scrollcopyrect detection with |
| *Keystroke* input: t1 is how long to wait after a key |
| is pressed for the first scroll, t2 is how long to keep |
| looking after a Keystroke scroll for more scrolls. |
| t3 is how frequently to try to update surrounding |
| scrollbars outside of the scrolling area (0.0 to |
| disable) |
| |
| "s1+s2+s3+s4+s5" specify five floating point times |
| in seconds that apply to scrollcopyrect detection with |
| *Mouse* input: s1 is how long to wait after a mouse |
| button is pressed for the first scroll, s2 is how long |
| to keep waiting for additional scrolls after the first |
| Mouse scroll was detected. s3 is how frequently to |
| try to update surrounding scrollbars outside of the |
| scrolling area (0.0 to disable). s4 is how long to |
| buffer pointer motion (to try to get fewer, bigger |
| mouse scrolls). s5 is the maximum time to spend just |
| updating the scroll window without updating the rest |
| of the screen. |
| |
| -fixscreen string Periodically "repair" the screen based on settings |
| in "string". Hopefully you won't need this option, |
| it is intended for cases when the -scrollcopyrect or |
| -wirecopyrect features leave too many painting errors, |
| but it can be used for any scenario. This option |
| periodically performs costly operations and so |
| interactive response may be reduced when it is on. |
| You can use 3 Alt_L's (the Left "Alt" key) taps in |
| a row (as described under -scrollcopyrect) instead to |
| manually request a screen repaint when it is needed. |
| |
| "string" is a comma separated list of one or more of |
| the following: "V=t", "C=t", "X=t", and "8=t". |
| In these "t" stands for a time in seconds (it is |
| a floating point even though one should usually use |
| values > 2 to avoid wasting resources). V sets how |
| frequently the entire screen should be sent to viewers |
| (it is like the 3 Alt_L's). C sets how long to wait |
| after a CopyRect to repaint the full screen. X sets |
| how frequently to reread the full X11 framebuffer from |
| the X server and push it out to connected viewers. |
| Use of X should be rare, please report a bug if you |
| find you need it. 8= applies only for -8to24 mode: it |
| sets how often the non-default visual regions of the |
| screen (e.g. 8bpp windows) are refreshed. Examples: |
| -fixscreen V=10 -fixscreen C=10 |
| |
| -debug_scroll Turn on debugging info printout for the scroll |
| heuristics. "-ds" is an alias. Specify it multiple |
| times for more output. |
| |
| -noxrecord Disable any use of the RECORD extension. This is |
| currently used by the -scrollcopyrect scheme and to |
| monitor X server grabs. |
| |
| -grab_buster Some of the use of the RECORD extension can leave a |
| -nograb_buster tiny window for XGrabServer deadlock. This is only if |
| the whole-server grabbing application expects mouse or |
| keyboard input before releasing the grab. It is usually |
| a window manager that does this. x11vnc takes care to |
| avoid the problem, but if caught x11vnc will freeze. |
| Without -grab_buster, the only solution is to go the |
| physical display and give it some input to satisfy the |
| grabbing app. Or manually kill and restart the window |
| manager if that is feasible. With -grab_buster, x11vnc |
| will fork a helper thread and if x11vnc appears to be |
| stuck in a grab after a period of time (20-30 sec) then |
| it will inject some user input: button clicks, Escape, |
| mouse motion, etc to try to break the grab. If you |
| experience a lot of grab deadlock, please report a bug. |
| |
| -debug_grabs Turn on debugging info printout with respect to |
| XGrabServer() deadlock for -scrollcopyrect mode. |
| |
| -debug_sel Turn on debugging info printout with respect to |
| PRIMARY, CLIPBOARD, and CUTBUFFER0 selections. |
| |
| -pointer_mode n Various pointer motion update schemes. "-pm" is |
| an alias. The problem is pointer motion can cause |
| rapid changes on the screen: consider the rapid |
| changes when you drag a large window around opaquely. |
| Neither x11vnc's screen polling and vnc compression |
| routines nor the bandwidth to the vncviewers can keep |
| up these rapid screen changes: everything will bog down |
| when dragging or scrolling. So a scheme has to be used |
| to "eat" much of that pointer input before re-polling |
| the screen and sending out framebuffer updates. The |
| mode number "n" can be 0 to 4 and selects one of |
| the schemes desribed below. |
| |
| Note that the -wireframe and -scrollcopyrect modes |
| complement -pointer_mode by detecting (and improving) |
| certain periods of "rapid screen change". |
| |
| n=0: does the same as -nodragging. (all screen polling |
| is suspended if a mouse button is pressed.) |
| |
| n=1: was the original scheme used to about Jan 2004: |
| it basically just skips -input_skip keyboard or pointer |
| events before repolling the screen. |
| |
| n=2 is an improved scheme: by watching the current rate |
| of input events it tries to detect if it should try to |
| "eat" additional pointer events before continuing. |
| |
| n=3 is basically a dynamic -nodragging mode: it detects |
| when the mouse motion has paused and then refreshes |
| the display. |
| |
| n=4 attempts to measures network rates and latency, |
| the video card read rate, and how many tiles have been |
| changed on the screen. From this, it aggressively tries |
| to push screen "frames" when it decides it has enough |
| resources to do so. NOT FINISHED. |
| |
| The default n is 2. Note that modes 2, 3, 4 will skip |
| -input_skip keyboard events (but it will not count |
| pointer events). Also note that these modes are not |
| available in -threads mode which has its own pointer |
| event handling mechanism. |
| |
| To try out the different pointer modes to see which |
| one gives the best response for your usage, it is |
| convenient to use the remote control function, for |
| example "x11vnc -R pm:4" or the tcl/tk gui (Tuning -> |
| pointer_mode -> n). |
| |
| -input_skip n For the pointer handling when non-threaded: try to |
| read n user input events before scanning display. n < 0 |
| means to act as though there is always user input. |
| Default: 10 |
| |
| -allinput Have x11vnc read and process all available client input |
| before proceeding. |
| |
| -input_eagerly Similar to -allinput but use the handleEventsEagerly |
| mechanism built into LibVNCServer. |
| |
| -speeds rd,bw,lat x11vnc tries to estimate some speed parameters that |
| are used to optimize scheduling (e.g. -pointer_mode |
| 4, -wireframe, -scrollcopyrect) and other things. |
| Use the -speeds option to set these manually. |
| The triple "rd,bw,lat" corresponds to video h/w |
| read rate in MB/sec, network bandwidth to clients in |
| KB/sec, and network latency to clients in milliseconds, |
| respectively. If a value is left blank, e.g. "-speeds |
| ,100,15", then the internal scheme is used to estimate |
| the empty value(s). |
| |
| Typical PC video cards have read rates of 5-10 MB/sec. |
| If the framebuffer is in main memory instead of video |
| h/w (e.g. SunRay, shadowfb, dummy driver, Xvfb), the |
| read rate may be much faster. "x11perf -getimage500" |
| can be used to get a lower bound (remember to factor |
| in the bytes per pixel). It is up to you to estimate |
| the network bandwith and latency to clients. For the |
| latency the ping(1) command can be used. |
| |
| For convenience there are some aliases provided, |
| e.g. "-speeds modem". The aliases are: "modem" for |
| 6,4,200; "dsl" for 6,100,50; and "lan" for 6,5000,1 |
| |
| -wmdt string For some features, e.g. -wireframe and -scrollcopyrect, |
| x11vnc has to work around issues for certain window |
| managers or desktops (currently kde and xfce). |
| By default it tries to guess which one, but it can |
| guess incorrectly. Use this option to indicate which |
| wm/dt. "string" can be "gnome", "kde", "cde", |
| "xfce", or "root" (classic X wm). Anything else |
| is interpreted as "root". |
| |
| -debug_pointer Print debugging output for every pointer event. |
| -debug_keyboard Print debugging output for every keyboard event. |
| Same as -dp and -dk, respectively. Use multiple |
| times for more output. |
| |
| -defer time Time in ms to delay sending updates to connected clients |
| (deferUpdateTime) Default: 20 |
| |
| -wait time Time in ms to pause between screen polls. Used to cut |
| down on load. Default: 20 |
| |
| -extra_fbur n Perform extra FrameBufferUpdateRequests checks to |
| try to be in better sync with the client's requests. |
| What this does is perform extra polls of the client |
| socket at critical times (before '-defer' and '-wait' |
| calls.) The default is n=1. Set to a larger number to |
| insert more checks or set to n=0 to disable. A downside |
| of these extra calls is that more mouse input may be |
| processed than desired. |
| |
| -wait_ui factor Factor by which to cut the -wait time if there |
| has been recent user input (pointer or keyboard). |
| Improves response, but increases the load whenever you |
| are moving the mouse or typing. Default: 2.00 |
| -setdefer n When the -wait_ui mechanism cuts down the wait time ms, |
| set the defer time to the same ms value. n=1 to enable, |
| 0 to disable, and -1 to set defer to 0 (no delay). |
| Similarly, 2 and -2 indicate 'urgent_update' mode should |
| be used to push the updates even sooner. Default: 1 |
| -nowait_bog Do not detect if the screen polling is "bogging down" |
| and sleep more. Some activities with no user input can |
| slow things down a lot: consider a large terminal window |
| with a long build running in it continuously streaming |
| text output. By default x11vnc will try to detect this |
| (3 screen polls in a row each longer than 0.25 sec with |
| no user input), and sleep up to 1.5 secs to let things |
| "catch up". Use this option to disable that detection. |
| -slow_fb time Floating point time in seconds to delay all screen |
| polling. For special purpose usage where a low frame |
| rate is acceptable and desirable, but you want the |
| user input processed at the normal rate so you cannot |
| use -wait. |
| -xrefresh time Floating point time in seconds to indicate how often to |
| do the equivalent of xrefresh(1) to force all windows |
| (in the viewable area if -id, -sid, or -clip is used) |
| to repaint themselves. Use this only if applications |
| misbehave by not repainting themselves properly. |
| See also -noxdamage. |
| -nap Monitor activity and if it is low take longer naps |
| -nonap between screen polls to really cut down load when idle. |
| Default: take naps |
| -sb time Time in seconds after NO activity (e.g. screen blank) |
| to really throttle down the screen polls (i.e. sleep |
| for about 1.5 secs). Use 0 to disable. Default: 60 |
| Set the env. var. X11VNC_SB_FACTOR to scale it. |
| |
| -readtimeout n Set LibVNCServer rfbMaxClientWait to n seconds. On |
| slow links that take a long time to paint the first |
| screen LibVNCServer may hit the timeout and drop the |
| connection. Default: 20 seconds. |
| -ping n Send a 1x1 framebuffer update to all clients every n |
| seconds (e.g. to try to keep a network connection alive) |
| |
| -nofbpm If the system supports the FBPM (Frame Buffer Power |
| -fbpm Management) extension (i.e. some Sun systems), then |
| prevent the video h/w from going into a reduced power |
| state when VNC clients are connected. |
| |
| FBPM capable video h/w save energy when the workstation |
| is idle by going into low power states (similar to DPMS |
| for monitors). This interferes with x11vnc's polling |
| of the framebuffer data. |
| |
| "-nofbpm" means prevent FBPM low power states whenever |
| VNC clients are connected, while "-fbpm" means to not |
| monitor the FBPM state at all. See the xset(1) manpage |
| for details. -nofbpm is basically the same as running |
| "xset fbpm force on" periodically. Default: -fbpm |
| |
| -nodpms If the system supports the DPMS (Display Power Managemen |
| t |
| -dpms Signaling) extension, then prevent the monitor from |
| going into a reduced power state when VNC clients |
| are connected. |
| |
| DPMS reduced power monitor states are a good thing |
| and you normally want the power down to take place |
| (usually x11vnc has no problem exporting the display in |
| this state). You probably only want to use "-nodpms" |
| to work around problems with Screen Savers kicking |
| on in DPMS low power states. There is known problem |
| with kdesktop_lock on KDE where the screen saver keeps |
| kicking in every time user input stops for a second |
| or two. Specifying "-nodpms" works around it. |
| |
| "-nodpms" means prevent DPMS low power states whenever |
| VNC clients are connected, while "-dpms" means to not |
| monitor the DPMS state at all. See the xset(1) manpage |
| for details. -nodpms is basically the same as running |
| "xset dpms force on" periodically. Default: -dpms |
| |
| -forcedpms If the system supports the DPMS (Display Power |
| Management Signaling) extension, then try to keep the |
| monitor in a powered off state. This is to prevent |
| nosey people at the physical display from viewing what |
| is on the screen. Be sure to lock the screen before |
| disconnecting. |
| |
| This method is far from bullet proof, e.g. suppose |
| someone attaches a non-DPMS monitor, or loads the |
| machine so that there is a gap of time before x11vnc |
| restores the powered off state? On many machines if |
| he floods it with keyboard and mouse input he can see |
| flashes of what is on the screen before the DPMS off |
| state is reestablished. For this to work securely |
| there would need to be support in the X server to do |
| this exactly rather than approximately with DPMS. |
| |
| -clientdpms As -forcedpms but only when VNC clients are connected. |
| |
| -noserverdpms The UltraVNC ServerInput extension is supported. |
| This allows the VNC viewer to click a button that will |
| cause the server (x11vnc) to try to disable keyboard |
| and mouse input at the physical display and put the |
| monitor in dpms powered off state. Use this option to |
| skip powering off the monitor. |
| |
| -noultraext Disable the following UltraVNC extensions: SingleWindow |
| and ServerInput. The others managed by LibVNCServer |
| (textchat, 1/n scaling, rfbEncodingUltra) are not. |
| |
| -chatwindow Place a local UltraVNC chat window on the X11 display |
| that x11vnc is polling. That way the person on the VNC |
| viewer-side can chat with the person at the physical |
| X11 console. (e.g. helpdesk w/o telephone) |
| |
| For this to work the SSVNC package (version 1.0.21 or |
| later) MUST BE installed on the system where x11vnc runs |
| and the 'ssvnc' command must be available in $PATH. |
| The ssvncviewer is used as a chat window helper. |
| See http://www.karlrunge.com/x11vnc/ssvnc.html |
| |
| This option implies '-rfbversion 3.6' so as to trick |
| UltraVNC viewers, otherwise they assume chat is not |
| available. To specify a different rfbversion, place |
| it after the -chatwindow option on the cmdline. |
| |
| See also the remote control 'chaton' and 'chatoff' |
| actions. These can also be set from the tkx11vnc GUI. |
| |
| -noxdamage Do not use the X DAMAGE extension to detect framebuffer |
| changes even if it is available. Use -xdamage if your |
| default is to have it off. |
| |
| x11vnc's use of the DAMAGE extension: 1) significantly |
| reduces the load when the screen is not changing much, |
| and 2) detects changed areas (small ones by default) |
| more quickly. |
| |
| Currently the DAMAGE extension is overly conservative |
| and often reports large areas (e.g. a whole terminal |
| or browser window) as damaged even though the actual |
| changed region is much smaller (sometimes just a few |
| pixels). So heuristics were introduced to skip large |
| areas and use the damage rectangles only as "hints" |
| for the traditional scanline polling. The following |
| tuning parameters are introduced to adjust this |
| behavior: |
| |
| -xd_area A Set the largest DAMAGE rectangle area "A" (in |
| pixels: width * height) to trust as truly damaged: |
| the rectangle will be copied from the framebuffer |
| (slow) no matter what. Set to zero to trust *all* |
| rectangles. Default: 20000 |
| -xd_mem f Set how long DAMAGE rectangles should be "remembered", |
| "f" is a floating point number and is in units of the |
| scanline repeat cycle time (32 iterations). The default |
| (1.0) should give no painting problems. Increase it if |
| there are problems or decrease it to live on the edge |
| (perhaps useful on a slow machine). |
| |
| -sigpipe string Broken pipe (SIGPIPE) handling. "string" can be |
| "ignore" or "exit". For "ignore" LibVNCServer |
| will handle the abrupt loss of a client and continue, |
| for "exit" x11vnc will cleanup and exit at the 1st |
| broken connection. |
| |
| This option is not really needed since LibVNCServer |
| is doing the correct thing now for quite some time. |
| However, for convenience you can use it to ignore other |
| signals, e.g. "-sigpipe ignore:HUP,INT,TERM" in case |
| that would be useful for some sort of application. |
| You can also put "exit:.." in the list to have x11vnc |
| cleanup on the listed signals. "-sig" is an alias |
| for this option if you don't like the 'pipe'. Example: |
| -sig ignore:INT,TERM,exit:USR1 |
| |
| -threads Whether or not to use the threaded LibVNCServer |
| -nothreads algorithm [rfbRunEventLoop] if libpthread is available. |
| In this mode new threads (one for input and one |
| for output) are created to handle each new client. |
| Default: -nothreads. |
| |
| Thread stability is much improved in version 0.9.8. |
| |
| Multiple clients in threaded mode should be stable |
| for the ZRLE encoding on all platforms. The Tight and |
| Zlib encodings are currently only stable on Linux for |
| multiple clients. Compile with -DTLS=__thread if your |
| OS and compiler and linker support it. |
| |
| For resizes (randr, etc.) set this env. var. to the numb |
| er |
| of milliseconds to sleep: X11VNC_THREADS_NEW_FB_SLEEP |
| at various places in the do_new_fb() action. This is to |
| let various activities settle. Default is about 500ms. |
| |
| Multiple clients in threaded mode could yield better |
| performance for 'class-room' broadcasting usage; also in |
| -appshare broadcast mode. See also the -reflect option. |
| |
| -fs f If the fraction of changed tiles in a poll is greater |
| than f, the whole screen is updated. Default: 0.75 |
| -gaps n Heuristic to fill in gaps in rows or cols of n or |
| less tiles. Used to improve text paging. Default: 4 |
| -grow n Heuristic to grow islands of changed tiles n or wider |
| by checking the tile near the boundary. Default: 3 |
| -fuzz n Tolerance in pixels to mark a tiles edges as changed. |
| Default: 2 |
| -debug_tiles Print debugging output for tiles, fb updates, etc. |
| |
| -snapfb Instead of polling the X display framebuffer (fb) |
| for changes, periodically copy all of X display fb |
| into main memory and examine that copy for changes. |
| (This setting also applies for non-X -rawfb modes). |
| Under some circumstances this will improve interactive |
| response, or at least make things look smoother, but in |
| others (most!) it will make the response worse. If the |
| video h/w fb is such that reading small tiles is very |
| slow this mode could help. To keep the "framerate" |
| up the screen size x bpp cannot be too large. Note that |
| this mode is very wasteful of memory I/O resources |
| (it makes full screen copies even if nothing changes). |
| It may be of use in video capture-like applications, |
| webcams, or where window tearing is a problem. |
| |
| -rawfb string Instead of polling X, poll the memory object specified |
| in "string". |
| |
| For file polling, to memory map mmap(2) a file use: |
| "map:/path/to/a/file@WxHxB", with framebuffer Width, |
| Height, and Bits per pixel. "mmap:..." is the |
| same. |
| |
| If there is trouble with mmap, use "file:/..." |
| for slower lseek(2) based reading. |
| |
| Use "snap:..." to imply -snapfb mode and the "file:" |
| access (this is for unseekable devices that only provide |
| the fb all at once, e.g. a video camera provides the |
| whole frame). |
| |
| For shared memory segments string is of the form: |
| "shm:N@WxHxB" which specifies a shmid N and with |
| WxHxB as above. See shmat(1) and ipcs(1) |
| |
| If you do not supply a type "map" is assumed if |
| the file exists (see the next paragraphs for some |
| exceptions to this.) |
| |
| If string is "setup:cmd", then the command "cmd" |
| is run and the first line from it is read and used |
| as "string". This allows initializing the device, |
| determining WxHxB, etc. These are often done as root |
| so take care. |
| |
| If the string begins with "video", see the VIDEO4LINUX |
| discussion below where the device may be queried for |
| (and possibly set) the framebuffer parameters. |
| |
| If the string begins with "console", "/dev/fb", |
| "fb", or "vt", see the LINUX CONSOLE discussion |
| below where the framebuffer device is opened and |
| keystrokes (and possibly mouse events) are inserted |
| into the console. |
| |
| If the string begins with "vnc", see the VNC HOST |
| discussion below where the framebuffer is taken as that |
| of another remote VNC server. |
| |
| Optional suffixes are ":R/G/B" and "+O" to specify |
| red, green, and blue masks (in hex) and an offset into |
| the memory object. If the masks are not provided x11vnc |
| guesses them based on the bpp (if the colors look wrong, |
| you need to provide the masks.) |
| |
| Another optional suffix is the Bytes Per Line which in |
| some cases is not WxB/8. Specify it as WxHxB-BPL |
| e.g. 800x600x16-2048. This could be a normal width |
| 1024 at 16bpp fb, but only width 800 shows up. |
| |
| So the full format is: mode:file@WxHxB:R/G/B+O-BPL |
| |
| Examples: |
| -rawfb shm:210337933@800x600x32:ff/ff00/ff0000 |
| -rawfb map:/dev/fb0@1024x768x32 |
| -rawfb map:/tmp/Xvfb_screen0@640x480x8+3232 |
| -rawfb file:/tmp/my.pnm@250x200x24+37 |
| -rawfb file:/dev/urandom@128x128x8 |
| -rawfb snap:/dev/video0@320x240x24 -24to32 |
| -rawfb video0 |
| -rawfb video -pipeinput VID |
| -rawfb console |
| -rawfb vt2 |
| -rawfb vnc:somehost:0 |
| |
| (see ipcs(1) and fbset(1) for the first two examples) |
| |
| In general all user input is discarded by default (see |
| the -pipeinput option for how to use a helper program |
| to insert). Most of the X11 (screen, keyboard, mouse) |
| options do not make sense and many will cause this |
| mode to crash, so please think twice before setting or |
| changing them in a running x11vnc. |
| |
| If you DO NOT want x11vnc to close the X DISPLAY in |
| rawfb mode, prepend a "+" e.g. +file:/dev/fb0... |
| Keeping the display open enables the default |
| remote-control channel, which could be useful. |
| Alternatively, if you specify -noviewonly, then the |
| mouse and keyboard input are STILL sent to the X |
| display, this usage should be very rare, i.e. doing |
| something strange with /dev/fb0. |
| |
| If the device is not "seekable" (e.g. webcam) try |
| reading it all at once in full snaps via the "snap:" |
| mode (note: this is a resource hog). If you are using |
| file: or map: AND the device needs to be reopened for |
| *every* snapfb snapshot, set the environment variable: |
| SNAPFB_RAWFB_RESET=1 as well. |
| |
| If you want x11vnc to dynamically transform a 24bpp |
| rawfb to 32bpp (note that this will be slower) also |
| supply the -24to32 option. This would be useful for, |
| say, a video camera that delivers the pixel data as |
| 24bpp packed RGB. This is the default under "video" |
| mode if the bpp is 24. |
| |
| Normally the bits per pixel, B, is 8, 16, or 32 (or |
| rarely 24), however there is also some support for |
| B < 8 (e.g. old graphics displays 4 bpp or 1 bpp). |
| In this case you certainly must supply the masks as |
| well: WxHxB:R/G/B. The pixels will be padded out to |
| 8 bpp using depth 8 truecolor. The scheme currently |
| does not work with snap fb (ask if interested.) B=1 |
| monochrome example: file:/dev/urandom@128x128x1:1/1/1 |
| Some other like this are 128x128x2:3/3/3 128x128x4:7/7/7 |
| |
| For B < 8 framebuffers you can also set the env. var |
| RAWFB_CGA=1 to try a CGA mapping for B=4 (e.g. linux |
| vga16fb driver.) Note with low bpp and/or resolution |
| VGA and VGA16 modes on the Linux console one's attempt |
| to export them via x11vnc can often be thwarted due to |
| special color palettes, pixel packings, and even video |
| painting buffering. OTOH, often experimenting with the |
| RGB masks can yield something recognizable. |
| |
| VIDEO4LINUX: on Linux some attempt is made to handle |
| video devices (webcams or TV tuners) automatically. |
| The idea is the WxHxB will be extracted from the |
| device itself. So if you do not supply "@WxHxB... |
| parameters x11vnc will try to determine them. It first |
| tries the v4l API if that support has been compiled in. |
| Otherwise it will run the v4l-info(1) external program |
| if it is available. |
| |
| The simplest examples are "-rawfb video" and "-rawfb |
| video1" which imply the device file /dev/video and |
| /dev/video1, respectively. You can also supply the |
| /dev if you like, e.g. "-rawfb /dev/video0" |
| |
| Since the video capture device framebuffer usually |
| changes continuously (e.g. brightness fluctuations), |
| you may want to use the -wait, -slow_fb, or -defer |
| options to lower the "framerate" to cut down on |
| network VNC traffic. |
| |
| A more sophisticated video device scheme allows |
| initializing the device's settings using: |
| |
| -rawfb video:<settings> |
| |
| The prefix could also be, as above, e.g. "video1:" to |
| specify the device file. The v4l API must be available |
| for this to work. Otherwise, you will need to try |
| to initialize the device with an external program, |
| e.g. xawtv, spcaview, and hope they persist when x11vnc |
| re-opens the device. |
| |
| <settings> is a comma separated list of key=value pairs. |
| The device's brightness, color, contrast, and hue can |
| be set to percentages, e.g. br=80,co=50,cn=44,hu=60. |
| |
| The device filename can be set too if needed (if it |
| does not start with "video"), e.g. fn=/dev/qcam. |
| |
| The width, height and bpp of the framebuffer can be |
| set via, e.g., w=160,h=120,bpp=16. |
| |
| Related to the bpp above, the pixel format can be set |
| via the fmt=XXX, where XXX can be one of: GREY, HI240, |
| RGB555, RGB565, RGB24, and RGB32 (with bpp 8, 8, 16, 16, |
| 24, and 32 respectively). See http://www.linuxtv.org |
| for more info (V4L api). |
| |
| For TV/rf tuner cards one can set the tuning mode |
| via tun=XXX where XXX can be one of PAL, NTSC, SECAM, |
| or AUTO. |
| |
| One can switch the input channel by the inp=XXX setting, |
| where XXX is the name of the input channel (Television, |
| Composite1, S-Video, etc). Use the name that is in the |
| information about the device that is printed at startup. |
| |
| For input channels with tuners (e.g. Television) one |
| can change which station is selected by the sta=XXX |
| setting. XXX is the station number. Currently only |
| the ntsc-cable-us (US cable) channels are built into |
| x11vnc. See the -freqtab option below to supply one |
| from xawtv. If XXX is greater than 500, then it is |
| interpreted as a raw frequency in KHz. |
| |
| Example: |
| |
| -rawfb video:br=80,w=320,h=240,fmt=RGB32,tun=NTSC,sta=47 |
| |
| one might need to add inp=Television too for the input |
| channel to be TV if the card doesn't come up by default |
| in that one. |
| |
| Note that not all video capture devices will support |
| all of the above settings. |
| |
| See the -pipeinput VID option below for a way to control |
| the settings through the VNC Viewer via keystrokes. |
| As a shortcut, if the string begins "Video.." instead |
| of "video.." then -pipeinput VID is implied. |
| |
| As above, if you specify a "@WxHxB..." after the |
| <settings> string they are used verbatim: the device |
| is not queried for the current values. Otherwise the |
| device will be queried. |
| |
| LINUX CONSOLE: The following describes some ways to |
| view and possibly interact with the Linux text/graphics |
| console (i.e. not X11 XFree86/Xorg) |
| |
| Note: If the LibVNCServer LinuxVNC program is on your |
| system you may want to use that instead of the following |
| method because it will be faster and more accurate |
| for the Linux text console and includes mouse support. |
| There is, however, the basic LinuxVNC functionality in |
| x11vnc if you replace "console" with "vt" in the |
| examples below. |
| |
| If the rawfb string begins with "console" the |
| framebuffer device /dev/fb0 is opened and /dev/tty0 is |
| opened too. The latter is used to inject keystrokes |
| (not all are supported, but the basic ones are). |
| You will need to be root to inject keystrokes, but |
| not necessarily to open /dev/fb0. /dev/tty0 refers to |
| the active VT, to indicate one explicitly, use, e.g., |
| "console2" for /dev/tty2, etc. by indicating the |
| specific VT number. |
| |
| For the Linux framebuffer device, /dev/fb0, (fb1, |
| etc) to be enabled the appropriate kernel drivers must |
| be loaded. E.g. vesafb or vga16fb and also by setting |
| the boot parameter vga=0x301 (or 0x314, 0x317, etc.) |
| (The vga=... method is the preferred way; set your |
| machines up that way.) Otherwise there will be a |
| 'No such device' error. You can also load a Linux |
| framebuffer driver specific to your make of video card |
| for more functionality. Once the machine is booted one |
| can often 'modprobe' the fb driver as root to obtain |
| a framebuffer device. |
| |
| If you cannot get /dev/fb0 working on Linux, try |
| using the LinuxVNC emulation mode by "-rawfb vtN" |
| where N = 1, ... 6 is the Linux Virtual Terminal (aka |
| virtual console) you wish to view, e.g. "-rawfb vt2". |
| Unlike /dev/fb mode, it need not be the active Virtual |
| Terminal. Note that this mode can only show text and |
| not graphics. x11vnc polls the text in /dev/vcsaN |
| |
| Set the env. var. RAWFB_VCSA_BW=1 to disable colors in |
| the "vtN" mode (i.e. black and white only.) If you |
| do not prefer the default 16bpp set RAWFB_VCSA_BPP to |
| 8 or 32. If you need to tweak the rawfb parameters by |
| using the 'console_guess' string printed at startup, |
| be sure to indicate the snap: method. |
| |
| uinput: If the Linux version appears to be 2.6 |
| or later and the "uinput" module appears to be |
| present (modprobe uinput), then the uinput method |
| will be used instead of /dev/ttyN. uinput allows |
| insertion of BOTH keystrokes and mouse input and so it |
| preferred when accessing graphical (e.g. QT-embedded) |
| linux console apps. It also provides more accurate |
| keystroke insertion. See -pipeinput UINPUT below for |
| more information on this mode; you will have to use |
| -pipeinput if you want to tweak any UINPUT parameters. |
| You may also want to also use the -nodragging and |
| -cursor none options. Use "console0", etc or |
| -pipeinput CONSOLE to force the /dev/ttyN method. |
| |
| Note you can change the Linux VT remotely using the |
| chvt(1) command to make the one you want be the active |
| one (e.g. 'chvt 3'). Sometimes switching out and back |
| corrects the framebuffer's graphics state. For the |
| "-rawfb vtN" mode there is no need to switch the VT's. |
| |
| To skip input injecting entirely use "consolex" |
| or "vtx". |
| |
| The string "/dev/fb0" (1, etc.) can be used instead |
| of "console". This can be used to specify a different |
| framebuffer device, e.g. /dev/fb1. As a shortcut the |
| "/dev/" can be dropped. If the name is something |
| nonstandard, use "console:/dev/foofb" |
| |
| If you do not want x11vnc to guess the framebuffer's |
| WxHxB and masks automatically (sometimes the kernel |
| gives incorrect information), specify them with a @WxHxB |
| (and optional :R/G/B masks) at the end of the string. |
| |
| Examples: |
| -rawfb console |
| -rawfb /dev/fb0 (same) |
| -rawfb console3 (force /dev/tty3) |
| -rawfb consolex (no keystrokes or mouse) |
| -rawfb console:/dev/nonstd |
| -rawfb console -pipeinput UINPUT:accel=4.0 |
| -rawfb vt3 (/dev/tty3 w/o /dev/fb0) |
| |
| VNC HOST: if the -rawfb string is of the form |
| "vnc:host:N" then the VNC display "N" on the remote |
| VNC server "host" is connected to (i.e. x11vnc acts as |
| a VNC client itself) and that framebuffer is exported. |
| |
| This mode is really only of use if you are trying |
| to improve performance in the case of many (e.g. > |
| 10) simultaneous VNC viewers, and you try a divide |
| and conquer scheme to reduce bandwidth and improve |
| responsiveness. (However, another user found this mode |
| useful to export a demo display through a slow link: |
| then multiple demo viewers connected to the reflecting |
| x11vnc on the fast side of the link, and so avoided |
| all of the demo viewers going through the slow link.) |
| |
| For example, if there will be 64 simultaneous VNC |
| viewers this can lead to a lot of redundant VNC traffic |
| to and from the server host:N, extra CPU usage, |
| and all viewers response can be reduced by having |
| to wait for writes to the slowest client to finish. |
| However, if you set up 8 reflectors/repeaters started |
| with option -rawfb vnc:host:N, then there are only |
| 8 connections to host:N. Each repeater then handles |
| 8 vnc viewer connections thereby spreading the load |
| around. In classroom broadcast usage, try to put the |
| repeaters on different switches. This mode is the same |
| as -reflect host:N. Replace "host:N" by "listen" |
| or "listen:port" for a reverse connection. |
| |
| Overall performance will not be as good as a single |
| direct connection because, among other things, |
| there is an additional level of framebuffer polling |
| and pointer motion can still induce many changes per |
| second that must be propagated. Tip: if the remote VNC |
| is x11vnc doing wireframing, or an X display that does |
| wireframing that gives much better response than opaque |
| window dragging. Consider the -nodragging option if |
| the problem is severe. |
| |
| The env. var. X11VNC_REFLECT_PASSWORD can be set to |
| the password needed to log into the vnc host server, or |
| to "file:path_to_file" to indicate a file containing |
| the password as its first line. |
| |
| To set the pixel format that x11vnc requests as a VNC |
| CLIENT set the env. vars: X11VNC_REFLECT_bitsPerSample |
| X11VNC_REFLECT_samplesPerPixel, and |
| X11VNC_REFLECT_bytesPerPixel; the defaults are 8, 3, 4. |
| 2, 3, 1 would give a low color mode. See the function |
| rfbGetClient() in libvncclient for more info. |
| |
| The VNC HOST mode implies -shared. Use -noshared as |
| a subsequent cmdline option to disable sharing. |
| |
| -freqtab file For use with "-rawfb video" for TV tuner devices to |
| specify station frequencies. Instead of using the built |
| in ntsc-cable-us mapping of station number to frequency, |
| use the data in file. For stations that are not |
| numeric, e.g. SE20, they are placed above the highest |
| numbered station in the order they are found. Example: |
| "-freqtab /usr/X11R6/share/xawtv/europe-west.list" |
| You can make your own freqtab by copying the xawtv |
| format. |
| |
| -pipeinput cmd This option lets you supply an external command in |
| "cmd" that x11vnc will pipe all of the user input |
| events to in a simple format. In -pipeinput mode by |
| default x11vnc will not process any of the user input |
| events. If you prefix "cmd" with "tee:" it will |
| both send them to the pipe command and process them. |
| For a description of the format run "-pipeinput |
| tee:/bin/cat". Another prefix is "reopen" which |
| means to reopen pipe if it exits. Separate multiple |
| prefixes with commas. |
| |
| In combination with -rawfb one might be able to |
| do amusing things (e.g. control non-X devices). |
| To facilitate this, if -rawfb is in effect then the |
| value is stored in X11VNC_RAWFB_STR for the pipe command |
| to use if it wants. Do 'env | grep X11VNC' for more. |
| |
| Built-in pipeinput modes (no external program required): |
| |
| If cmd is "VID" and you are using the -rawfb for a |
| video capture device, then an internal list of keyboard |
| mappings is used to set parameters of the video. |
| The mappings are: |
| |
| "B" and "b" adjust the brightness up and down. |
| "H" and "h" adjust the hue. |
| "C" and "c" adjust the colour. |
| "N" and "n" adjust the contrast. |
| "S" and "s" adjust the size of the capture screen. |
| "I" and "i" cycle through input channels. |
| Up and Down arrows adjust the station (if a tuner) |
| F1, F2, ..., F6 will switch the video capture pixel |
| format to HI240, RGB565, RGB24, RGB32, RGB555, and |
| GREY respectively. See -rawfb video for details. |
| |
| If cmd is "CONSOLE" or "CONSOLEn" where n |
| is a Linux console number, then the linux console |
| keystroke insertion to /dev/ttyN (see -rawfb console) |
| is performed. |
| |
| If cmd begins with "UINPUT" then the Linux uinput |
| module is used to insert both keystroke and mouse events |
| to the Linux console (see -rawfb above). This usually |
| is the /dev/input/uinput device file (you may need to |
| create it with "mknod /dev/input/uinput c 10 223" |
| and insert the module with "modprobe uinput". |
| |
| The UINPUT mode currently only does US keyboards (a |
| scan code option may be added), and not all keysyms |
| are supported. But it is probably more accurate than |
| the "CONSOLE" method. |
| |
| You may want to use the options -cursor none and |
| -nodragging in this mode. |
| |
| Additional tuning options may be supplied via: |
| UINPUT:opt1,opt2,... (a comma separated list). If an |
| option begins with "/" it is taken as the uinput |
| device file. |
| |
| Which uinput is injected can be controlled by an option |
| string made of the characters "K", "M", and "B" |
| (see the -input option), e.g. "KM" allows keystroke |
| and motion but not button clicks. |
| |
| A UINPUT option of the form: accel=f, or accel=fx+fy |
| sets the mouse motion "acceleration". This is used |
| to correct raw mouse relative motion into how much the |
| application cursor moves (x11vnc has no control over, |
| or knowledge of how the windowing application interprets |
| the raw mouse motions). Typically the acceleration |
| for an X display is 2 (see xset "m" option). "f" |
| is a floating point number, e.g. 3.0. Use "fx+fy" |
| if you need to supply different corrections for x and y. |
| |
| Note: the default acceleration is 2.0 since it seems |
| both X and qt-embedded often (but not always) use |
| this value. |
| |
| Even with a correct accel setting the mouse position |
| will get out of sync (probably due to a mouse |
| "threshold" setting where the acceleration doe not |
| apply, set xset(1)). The option reset=N sets the |
| number of ms (default 150) after which the cursor is |
| attempted to be reset (by forcing the mouse to (0, |
| 0) via small increments and then back out to (x, y) |
| in 1 jump), This correction seems to be needed but can |
| cause jerkiness or unexpected behavior with menus, etc. |
| Use reset=0 to disable. |
| |
| If you set the env. var X11VNC_UINPUT_THRESHOLDS then |
| the thresh=n mode will be enabled. It is currently |
| not working well. If |dx| <= thresh and |dy| < thresh |
| no acceleration is applied. Use "thresh=+n" |dx| + |
| |dy| < thresh to be used instead (X11?) |
| |
| Example: |
| -pipeinput UINPUT:accel=4.0 -cursor none |
| |
| If the uinput device has an absolute pointer (as opposed |
| to a normal mouse that is a relative pointer) you can |
| specify the option "abs". Note that a touchpad |
| on a laptop is an absolute device to some degree. |
| This (usually) avoids all the problems with mouse |
| acceleration. If x11vnc has trouble deducing the |
| size of the device, use "abs=WxH". Furthermore, |
| if the device is a touchscreen (assumed to have an |
| absolute pointer) use "touch" or "touch=WxH". |
| For touchscreens, when a mouse button is pressed, |
| a pressure increase is injected, and when the button |
| is released a pressure of zero is injected. |
| |
| If touch has been set, use "touch_always=1" to |
| indicate whenever the mouse moves with no button |
| pressed, a touch event of zero pressure should be |
| sent anyway. Also use "btn_touch=1" to indicate a |
| BTN_TOUCH keystroke press or release should be sent |
| instead of a pressure change. Set "dragskip=n" to |
| skip n dragged mouse touches (with pressure applied) |
| before injecting one. To indicate the pressure that |
| should be sent when there is a button click for a |
| touchscreen device, specify pressure=n, e.g. n=5. The |
| default is n=1. |
| |
| If a touch screen is being used ("touch" above) |
| and it is having its input processed by tslib, you can |
| specify the tslib calibration file via tslib_cal=<file>. |
| For example, tslib_cal=/etc/pointercal. To get accurate |
| or even usable positioning this is required when tslib |
| is in use. |
| |
| The Linux uinput mechanism can be bypassed and one can |
| write input events DIRECTLY to the devices instead. |
| To do this, specify one or more of the following |
| for the input classes: direct_rel=<device> |
| direct_abs=<device> direct_btn=<device> or |
| direct_key=<device>. The <device> file is usually |
| something like /dev/input/event1 but you can specify |
| any device file or pipe. You must specify each one |
| of the above classes even if they correspond to the |
| same device file (rel/abs and btn are often the same.) |
| Look at the file /proc/bus/input/devices to get an idea |
| what is available and the device filenames. Note: |
| The /dev/input/mouse* devices do not seem to work, |
| use the corresponding /dev/input/event* file instead. |
| Any input class not directly specified as above will be |
| handled via the uinput mechanism. To disable creating a |
| uinput device (and thereby discarding unhandled input), |
| specify "nouinput". |
| |
| Examples: |
| |
| -pipeinput UINPUT:direct_abs=/dev/input/event1 |
| |
| this was used on a qtmoko Neo freerunner (armel): |
| |
| -pipeinput UINPUT:touch,tslib_cal=/etc/pointercal, |
| direct_abs=/dev/input/event1,nouinput,dragskip=4 |
| |
| (where the long line has been split into two.) |
| |
| You can set the env. var X11VNC_UINPUT_DEBUG=1 or higher |
| to get debugging output for UINPUT mode. |
| |
| -macnodim For the native MacOSX server, disable dimming. |
| -macnosleep For the native MacOSX server, disable display sleep. |
| -macnosaver For the native MacOSX server, disable screensaver. |
| -macnowait For the native MacOSX server, do not wait for the |
| user to switch back to his display. |
| -macwheel n For the native MacOSX server, set the mouse wheel |
| speed to n (default 5). |
| -macnoswap For the native MacOSX server, do not swap mouse |
| buttons 2 and 3. |
| -macnoresize For the native MacOSX server, do not resize or reset |
| the framebuffer even if it is detected that the screen |
| resolution or depth has changed. |
| -maciconanim n For the native MacOSX server, set n to the number |
| of milliseconds that the window iconify/deiconify |
| animation takes. In -ncache mode this value will be |
| used to skip the animation if possible. (default 400) |
| -macmenu For the native MacOSX server, in -ncache client-side |
| caching mode, try to cache pull down menus (not perfect |
| because they have animated fades, etc.) |
| -macuskbd For the native MacOSX server, use the original |
| keystroke insertion code based on a US keyboard. |
| -macnoopengl For the native MacOSX server, do not use OpenGL for |
| screen capture, but rather use the original, deprecated |
| raw memory access method: addr = CGDisplayBaseAddress(). |
| -macnorawfb For the native MacOSX server, disable the raw memory |
| address screen capture method. |
| |
| MACOSX NOTE: There are some deprecated MacOSX interfaces |
| to inject keyboard and mouse events and the raw memory |
| access method is deprecated as well (however, OpenGL |
| will be preferred if available because it is faster.) |
| One can force not using any deprecated interfaces at |
| compile time by setting -DX11VNC_MACOSX_NO_DEPRECATED=1 |
| in CPPFLAGS. Or to turn them off one by one: |
| -DX11VNC_MACOSX_NO_DEPRECATED_LOCALEVENTS=1, |
| -DX11VNC_MACOSX_NO_DEPRECATED_POSTEVENTS=1 or |
| -DX11VNC_MACOSX_NO_DEPRECATED_FRAMEBUFFER=1 |
| At run time, for testing and workarounds, one can |
| disable them by using: |
| -env X11VNC_MACOSX_NO_DEPRECATED=1 |
| -env X11VNC_MACOSX_NO_DEPRECATED_LOCALEVENTS=1 |
| -env X11VNC_MACOSX_NO_DEPRECATED_POSTEVENTS=1 or |
| -env X11VNC_MACOSX_NO_DEPRECATED_FRAMEBUFFER=1 |
| Note: When doing either of these for the mouse input |
| not everything works currently, e.g. double clicks and |
| wireframing. Also, screen resolution and pixel depth |
| changes will not be automatically detected unless the |
| deprecated framebuffer interfaces are allowed. |
| |
| Conversely, if you are compiling on an |
| older machine that does not have some of |
| the newer interfaces, you may need to specify |
| -DX11VNC_MACOSX_NO_CGEVENTCREATESCROLLWHEELEVENT |
| -DX11VNC_MACOSX_NO_CGEVENTCREATEMOUSEEVENT or |
| -DX11VNC_MACOSX_NO_CGEVENTCREATEKEYBOARDEVENT. Use |
| -DX11VNC_MACOSX_USE_GETMAINDEVICE to regain the very |
| old QuickDraw GetMainDevice() interface (rare...) |
| |
| -gui [gui-opts] Start up a simple tcl/tk gui based on the remote |
| control options -remote/-query described below. |
| Requires the "wish" program to be installed on the |
| machine. "gui-opts" is not required: the default |
| is to start up both the full gui and x11vnc with the |
| gui showing up on the X display in the environment |
| variable DISPLAY. |
| |
| "gui-opts" can be a comma separated list of items. |
| Currently there are these types of items: 1) a gui |
| mode, a 2) gui "simplicity", 3) the X display the |
| gui should display on, 4) a "tray" or "icon" mode, |
| and 5) a gui geometry. |
| |
| 1) The gui mode can be "start", "conn", or "wait" |
| "start" is the default mode above and is not required. |
| "conn" means do not automatically start up x11vnc, |
| but instead just try to connect to an existing x11vnc |
| process. "wait" means just start the gui and nothing |
| else (you will later instruct the gui to start x11vnc |
| or connect to an existing one.) |
| |
| 2) The gui simplicity is off by default (a power-user |
| gui with all options is presented) To start with |
| something less daunting supply the string "simple" |
| ("ez" is an alias for this). Once the gui is |
| started you can toggle between the two with "Misc -> |
| simple_gui". |
| |
| 3) Note the possible confusion regarding the potentially |
| two different X displays: x11vnc polls one, but you |
| may want the gui to appear on another. For example, if |
| you ssh in and x11vnc is not running yet you may want |
| the gui to come back to you via your ssh redirected X |
| display (e.g. localhost:10). |
| |
| If you do not specify a gui X display in "gui-opts" |
| then the DISPLAY environment variable and -display |
| option are tried (in that order). Regarding the x11vnc |
| X display the gui will try to communication with, it |
| first tries -display and then DISPLAY. For example, |
| "x11vnc -display :0 -gui otherhost:0", will remote |
| control an x11vnc polling :0 and display the gui on |
| otherhost:0 The "tray/icon" mode below reverses this |
| preference, preferring to display on the x11vnc display. |
| |
| 4) When "tray" or "icon" is specified, the gui |
| presents itself as a small icon with behavior typical |
| of a "system tray" or "dock applet". The color |
| of the icon indicates status (connected clients) and |
| there is also a balloon status. Clicking on the icon |
| gives a menu from which properties, etc, can be set and |
| the full gui is available under "Advanced". To be |
| fully functional, the gui mode should be "start" |
| (the default). |
| |
| Note that tray or icon mode will imply the -forever |
| x11vnc option (if the x11vnc server is started along |
| with the gui) unless -connect or -connect_or_exit has |
| been specified. So x11vnc (and the tray/icon gui) |
| will wait for more connections after the first client |
| disconnects. If you want only one viewer connection |
| include the -once option. |
| |
| For "icon" the gui just a small standalone window. |
| For "tray" it will attempt to embed itself in the |
| "system tray" if possible. If "=setpass" is appended the |
| n |
| at startup the X11 user will be prompted to set the |
| VNC session password. If =<hexnumber> is appended |
| that icon will attempt to embed itself in the window |
| given by hexnumber. Use =noadvanced to disable the |
| full gui. (To supply more than one, use "+" sign). |
| E.g. -gui tray=setpass and -gui icon=0x3600028 |
| |
| Other modes: "full", the default and need not be |
| specified. "-gui none", do not show a gui, useful |
| to override a ~/.x11vncrc setting, etc. |
| |
| 5) When "geom=+X+Y" is specified, that geometry |
| is passed to the gui toplevel. This is the icon in |
| icon/tray mode, or the full gui otherwise. You can |
| also specify width and height, i.e. WxH+X+Y, but it |
| is not recommended. In "tray" mode the geometry is |
| ignored unless the system tray manager does not seem |
| to be running. One could imagine using something like |
| "-gui tray,geom=+4000+4000" with a display manager |
| to keep the gui invisible until someone logs in... |
| |
| More icon tricks, "icon=minimal" gives an icon just |
| with the VNC display number. You can also set the font |
| with "iconfont=...". The following could be useful: |
| "-gui icon=minimal,iconfont=5x8,geom=24x10+0-0" |
| |
| General examples of the -gui option: "x11vnc -gui", |
| "x11vnc -gui ez" "x11vnc -gui localhost:10", |
| "x11vnc -gui conn,host:0", "x11vnc -gui tray,ez" |
| "x11vnc -gui tray=setpass" |
| |
| If you do not intend to start x11vnc from the gui |
| (i.e. just remote control an existing one), then the |
| gui process can run on a different machine from the |
| x11vnc server as long as X permissions, etc. permit |
| communication between the two. |
| |
| FONTS: On some systems the tk fonts can be too small, |
| jagged, or otherwise unreadable. There are 4 env vars |
| you can set to be the tk font you prefer: |
| |
| X11VNC_FONT_BOLD main font for menus and buttons. |
| X11VNC_FONT_FIXED font for fixed width text. |
| |
| X11VNC_FONT_BOLD_SMALL tray icon font. |
| X11VNC_FONT_REG_SMALL tray icon menu font. |
| |
| The last two only apply for the tray icon mode. |
| |
| Here are some examples: |
| |
| -env X11VNC_FONT_BOLD='Helvetica -16 bold' |
| -env X11VNC_FONT_FIXED='Courier -14' |
| -env X11VNC_FONT_REG_SMALL='Helvetica -12' |
| |
| You can put the lines like the above (without the |
| quotes) in your ~/.x11vncrc file to avoid having to |
| specify them on the x11vnc command line. |
| |
| -remote command Remotely control some aspects of an already running |
| x11vnc server. "-R" and "-r" are aliases for |
| "-remote". After the remote control command is |
| sent to the running server the 'x11vnc -remote ...' |
| x11vnc command exits. You can often use the -query |
| command (see below) to see if the x11vnc server |
| processed your -remote command. |
| |
| The default communication channel is that of X |
| properties (specifically X11VNC_REMOTE), and so this |
| command must be run with correct settings for DISPLAY |
| and possibly XAUTHORITY to connect to the X server |
| and set the property. Alternatively, use the -display |
| and -auth options to set them to the correct values. |
| The running server cannot use the -novncconnect option |
| because that disables the communication channel. |
| See below for alternate channels. |
| |
| For example: 'x11vnc -remote stop' (which is the same as |
| 'x11vnc -R stop') will close down the x11vnc server. |
| 'x11vnc -R shared' will enable shared connections, and |
| 'x11vnc -R scale:3/4' will rescale the desktop. |
| |
| To use a different name for the X11 property (e.g. to |
| have separate communication channels for multiple |
| x11vnc's on the same display) set the X11VNC_REMOTE |
| environment variable to the string you want, for |
| example: -env X11VNC_REMOTE=X11VNC_REMOTE_12345 |
| Both sides of the channel must use the same unique name. |
| |
| To run a bunch of commands in a sequence use something |
| like: x11vnc -R 'script:firstcmd;secondcmd;...' |
| |
| Use x11vnc -R script:file=/path/to/file to read commands |
| from a file (can be multi-line and use the comment '#' |
| character in the normal way. The ';' separator must |
| still be used to separate each command.) |
| |
| To not try to contact another x11vnc process and instead |
| just run the command (or query) directly, prefix the |
| command with the string "DIRECT:" |
| |
| The following -remote/-R commands are supported: |
| |
| stop terminate the server, same as "quit" |
| "exit" or "shutdown". |
| ping see if the x11vnc server responds. |
| return is: ans=ping:<display> |
| ping:mystring as above, but use your own unique string |
| . |
| return is: ans=ping:mystring:<xdisplay> |
| blacken try to push a black fb update to all |
| clients (due to timings a client |
| could miss it). Same as "zero", also |
| "zero:x1,y1,x2,y2" for a rectangle. |
| refresh send the entire fb to all clients. |
| reset recreate the fb, polling memory, etc. |
| id:windowid set -id window to "windowid". empty |
| or "root" to go back to root window |
| sid:windowid set -sid window to "windowid" |
| id_cmd:cmd cmds: raise, lower, map, unmap, iconify, |
| move:dXdY, resize:dWdH, geom:WxH+X+Y. dX |
| dY, dW, and dH must have a leading "+" |
| or "-" e.g.: move:-30+10 resize:+20+35 |
| also: wm_delete, wm_name:string and |
| icon_name:string. Also id_cmd:win=N:cmd |
| waitmapped wait until subwin is mapped. |
| nowaitmapped do not wait until subwin is mapped. |
| clip:WxH+X+Y set -clip mode to "WxH+X+Y" |
| flashcmap enable -flashcmap mode. |
| noflashcmap disable -flashcmap mode. |
| shiftcmap:n set -shiftcmap to n. |
| notruecolor enable -notruecolor mode. |
| truecolor disable -notruecolor mode. |
| overlay enable -overlay mode (if applicable). |
| nooverlay disable -overlay mode. |
| overlay_cursor in -overlay mode, enable cursor drawing. |
| overlay_nocursor disable cursor drawing. same as |
| nooverlay_cursor. |
| 8to24 enable -8to24 mode (if applicable). |
| no8to24 disable -8to24 mode. |
| 8to24_opts:str set the -8to24 opts to "str". |
| 24to32 enable -24to32 mode (if applicable). |
| no24to32 disable -24to32 mode. |
| visual:vis set -visual to "vis" |
| scale:frac set -scale to "frac" |
| scale_cursor:f set -scale_cursor to "f" |
| viewonly enable -viewonly mode. |
| noviewonly disable -viewonly mode. |
| shared enable -shared mode. |
| noshared disable -shared mode. |
| forever enable -forever mode. |
| noforever disable -forever mode. |
| timeout:n reset -timeout to n, if there are |
| currently no clients, exit unless one |
| connects in the next n secs. |
| tightfilexfer enable filetransfer for NEW clients. |
| notightfilexfer disable filetransfer for NEW clients. |
| ultrafilexfer enable filetransfer for clients. |
| noultrafilexfer disable filetransfer for clients. |
| rfbversion:n.m set -rfbversion for new clients. |
| http enable http client connections. |
| nohttp disable http client connections. |
| deny deny any new connections, same as "lock" |
| nodeny allow new connections, same as "unlock" |
| avahi enable avahi service advertising. |
| noavahi disable avahi service advertising. |
| mdns enable avahi service advertising. |
| nomdns disable avahi service advertising. |
| zeroconf enable avahi service advertising. |
| nozeroconf disable avahi service advertising. |
| connect:host do reverse connection to host, "host" |
| may be a comma separated list of hosts |
| or host:ports. See -connect. Passwords |
| required as with fwd connections. |
| See X11VNC_REVERSE_CONNECTION_NO_AUTH=1 |
| disconnect:host disconnect any clients from "host" |
| same as "close:host". Use host |
| "all" to close all current clients. |
| If you know the client internal hex ID, |
| e.g. 0x3 (returned by "-query clients" |
| and RFB_CLIENT_ID) you can use that too. |
| proxy:host:port set reverse connection proxy (empty to |
| disable). |
| allowonce:host For the next connection only, allow |
| connection from "host". In -ssl mode |
| two connections are allowed (i.e. Fetch |
| Cert) unless X11VNC_NO_SSL_ALLOW_TWICE=1 |
| allow:hostlist set -allow list to (comma separated) |
| "hostlist". See -allow and -localhost. |
| Do not use with -allow /path/to/file |
| Use "+host" to add a single host, and |
| use "-host" to delete a single host |
| localhost enable -localhost mode |
| nolocalhost disable -localhost mode |
| listen:str set -listen to str, empty to disable. |
| noipv6 enable -noipv6 mode. |
| ipv6 disable -noipv6 mode. |
| noipv4 enable -noipv4 mode. |
| ipv4 disable -noipv4 mode. |
| 6 enable -6 IPv6 listening mode. |
| no6 disable -6 IPv6 listening mode. |
| lookup disable -nolookup mode. |
| nolookup enable -nolookup mode. |
| lookup disable -nolookup mode. |
| input:str set -input to "str", empty to disable. |
| grabkbd enable -grabkbd mode. |
| nograbkbd disable -grabkbd mode. |
| grabptr enable -grabptr mode. |
| nograbptr disable -grabptr mode. |
| grabalways enable -grabalways mode. |
| nograbalways disable -grabalways mode. |
| grablocal:n set -grablocal to n. |
| client_input:str set the K, M, B -input on a per-client |
| basis. select which client as for |
| disconnect, e.g. client_input:host:MB |
| or client_input:0x2:K |
| accept:cmd set -accept "cmd" (empty to disable). |
| afteraccept:cmd set -afteraccept (empty to disable). |
| gone:cmd set -gone "cmd" (empty to disable). |
| noshm enable -noshm mode. |
| shm disable -noshm mode (i.e. use shm). |
| flipbyteorder enable -flipbyteorder mode, you may need |
| to set noshm for this to do something. |
| noflipbyteorder disable -flipbyteorder mode. |
| onetile enable -onetile mode. (you may need to |
| set shm for this to do something) |
| noonetile disable -onetile mode. |
| solid enable -solid mode |
| nosolid disable -solid mode. |
| solid_color:color set -solid color (and apply it). |
| blackout:str set -blackout "str" (empty to disable). |
| See -blackout for the form of "str" |
| (basically: WxH+X+Y,...) |
| Use "+WxH+X+Y" to append a single |
| rectangle use "-WxH+X+Y" to delete one |
| xinerama enable -xinerama mode. (if applicable) |
| noxinerama disable -xinerama mode. |
| xtrap enable -xtrap input mode(if applicable) |
| noxtrap disable -xtrap input mode. |
| xrandr enable -xrandr mode. (if applicable) |
| noxrandr disable -xrandr mode. |
| xrandr_mode:mode set the -xrandr mode to "mode". |
| rotate:mode set the -rotate mode to "mode". |
| padgeom:WxH set -padgeom to WxH (empty to disable) |
| If WxH is "force" or "do" the padded |
| geometry fb is immediately applied. |
| quiet enable -quiet mode. |
| noquiet disable -quiet mode. |
| modtweak enable -modtweak mode. |
| nomodtweak enable -nomodtweak mode. |
| xkb enable -xkb modtweak mode. |
| noxkb disable -xkb modtweak mode. |
| capslock enable -capslock mode. |
| nocapslock disable -capslock mode. |
| skip_lockkeys enable -skip_lockkeys mode. |
| noskip_lockkeys disable -skip_lockkeys mode. |
| skip_keycodes:str enable -xkb -skip_keycodes "str". |
| sloppy_keys enable -sloppy_keys mode. |
| nosloppy_keys disable -sloppy_keys mode. |
| skip_dups enable -skip_dups mode. |
| noskip_dups disable -skip_dups mode. |
| add_keysyms enable -add_keysyms mode. |
| noadd_keysyms stop adding keysyms. those added will |
| still be removed at exit. |
| clear_mods enable -clear_mods mode and clear them. |
| noclear_mods disable -clear_mods mode. |
| clear_keys enable -clear_keys mode and clear them. |
| noclear_keys disable -clear_keys mode. |
| clear_locks do the clear_locks action. |
| clear_all do the clear_all action. |
| keystate have x11vnc print current keystate. |
| remap:str set -remap "str" (empty to disable). |
| See -remap for the form of "str" |
| (basically: key1-key2,key3-key4,...) |
| Use "+key1-key2" to append a single |
| keymapping, use "-key1-key2" to delete. |
| norepeat enable -norepeat mode. |
| repeat disable -norepeat mode. |
| nofb enable -nofb mode. |
| fb disable -nofb mode. |
| bell enable bell (if supported). |
| nobell disable bell. |
| sendbell ring the bell now. |
| nosel enable -nosel mode. |
| sel disable -nosel mode. |
| noprimary enable -noprimary mode. |
| primary disable -noprimary mode. |
| nosetprimary enable -nosetprimary mode. |
| setprimary disable -nosetprimary mode. |
| noclipboard enable -noclipboard mode. |
| clipboard disable -noclipboard mode. |
| nosetclipboard enable -nosetclipboard mode. |
| setclipboard disable -nosetclipboard mode. |
| seldir:str set -seldir to "str" |
| resend_cutbuffer resend the most recent CUTBUFFER0 copy |
| resend_clipboard resend the most recent CLIPBOARD copy |
| resend_primary resend the most recent PRIMARY copy |
| cursor:mode enable -cursor "mode". |
| show_cursor enable showing a cursor. |
| noshow_cursor disable showing a cursor. (same as |
| "nocursor") |
| cursor_drag enable cursor changes during drag. |
| nocursor_drag disable cursor changes during drag. |
| arrow:n set -arrow to alternate n. |
| xfixes enable xfixes cursor shape mode. |
| noxfixes disable xfixes cursor shape mode. |
| alphacut:n set -alphacut to n. |
| alphafrac:f set -alphafrac to f. |
| alpharemove enable -alpharemove mode. |
| noalpharemove disable -alpharemove mode. |
| alphablend disable -noalphablend mode. |
| noalphablend enable -noalphablend mode. |
| cursorshape disable -nocursorshape mode. |
| nocursorshape enable -nocursorshape mode. |
| cursorpos disable -nocursorpos mode. |
| nocursorpos enable -nocursorpos mode. |
| xwarp enable -xwarppointer mode. |
| noxwarp disable -xwarppointer mode. |
| always_inject enable -always_inject mode. |
| noalways_inject disable -always_inject mode. |
| buttonmap:str set -buttonmap "str", empty to disable |
| dragging disable -nodragging mode. |
| nodragging enable -nodragging mode. |
| ncache reenable -ncache mode. |
| noncache disable -ncache mode. |
| ncache_size:n set -ncache size to n. |
| ncache_cr enable -ncache_cr mode. |
| noncache_cr disable -ncache_cr mode. |
| ncache_no_moveraise enable no_moveraise mode. |
| noncache_no_moveraise disable no_moveraise mode. |
| ncache_no_dtchange enable ncache_no_dtchange mode. |
| noncache_no_dtchange disable ncache_no_dtchange mode. |
| ncache_old_wm enable ncache_old_wm mode. |
| noncache_old_wm disable ncache_old_wm mode. |
| ncache_no_rootpixmap enable ncache_no_rootpixmap. |
| noncache_no_rootpixmap disable ncache_no_rootpixmap. |
| ncache_reset_rootpixmap recheck the root pixmap, ncrp |
| ncache_keep_anims enable ncache_keep_anims. |
| noncache_keep_anims disable ncache_keep_anims. |
| ncache_pad:n set -ncache_pad to n. |
| wireframe enable -wireframe mode. same as "wf" |
| nowireframe disable -wireframe mode. same as "nowf" |
| wireframe:str enable -wireframe mode string. |
| wireframe_mode:str enable -wireframe mode string. |
| wireframelocal enable wireframelocal. same as "wfl" |
| nowireframe disable wireframelocal. same as "nowfl" |
| wirecopyrect:str set -wirecopyrect string. same as "wcr: |
| " |
| scrollcopyrect:str set -scrollcopyrect string. same "scr |
| " |
| noscrollcopyrect disable -scrollcopyrect mode. "noscr" |
| scr_area:n set -scr_area to n |
| scr_skip:list set -scr_skip to "list" |
| scr_inc:list set -scr_inc to "list" |
| scr_keys:list set -scr_keys to "list" |
| scr_term:list set -scr_term to "list" |
| scr_keyrepeat:str set -scr_keyrepeat to "str" |
| scr_parms:str set -scr_parms parameters. |
| fixscreen:str set -fixscreen to "str". |
| noxrecord disable all use of RECORD extension. |
| xrecord enable use of RECORD extension. |
| reset_record reset RECORD extension (if avail.) |
| pointer_mode:n set -pointer_mode to n. same as "pm" |
| input_skip:n set -input_skip to n. |
| allinput enable use of -allinput mode. |
| noallinput disable use of -allinput mode. |
| input_eagerly enable use of -input_eagerly mode. |
| noinput_eagerly disable use of -input_eagerly mode. |
| ssltimeout:n set -ssltimeout to n. |
| speeds:str set -speeds to str. |
| wmdt:str set -wmdt to str. |
| debug_pointer enable -debug_pointer, same as "dp" |
| nodebug_pointer disable -debug_pointer, same as "nodp" |
| debug_keyboard enable -debug_keyboard, same as "dk" |
| nodebug_keyboard disable -debug_keyboard, same as "nodk" |
| keycode:n inject keystroke 'keycode' (xmodmap -pk) |
| keycode:n,down inject 'keycode' (down=0,1) |
| keysym:str inject keystroke 'keysym' (number/name) |
| keysym:str,down inject 'keysym' (down=0,1) |
| ptr:x,y,mask inject pointer event x, y, button-mask |
| fakebuttonevent:button,down direct XTestFakeButtonEvent. |
| sleep:t sleep floating point time t. |
| get_xprop:p get X property named 'p'. |
| set_xprop:p:val set X property named 'p' to 'val'. |
| p -> id=NNN:p for hex/dec window id. |
| wininfo:id get info about X window id. use 'root' |
| for root window, use +id for children. |
| grab_state get state of pointer and keyboard grab. |
| pointer_pos print XQueryPointer x,y cursor position. |
| pointer_x print XQueryPointer x cursor position. |
| pointer_y print XQueryPointer y cursor position. |
| pointer_same print XQueryPointer ptr on same screen. |
| pointer_root print XQueryPointer curr ptr rootwin. |
| pointer_mask print XQueryPointer button and mods mask |
| mouse_x print x11vnc's idea of cursor position. |
| mouse_y print x11vnc's idea of cursor position. |
| noop do nothing. |
| defer:n set -defer to n ms,same as deferupdate:n |
| wait:n set -wait to n ms. |
| extra_fbur:n set -extra_fbur to n. |
| wait_ui:f set -wait_ui factor to f. |
| setdefer:n set -setdefer to -2,-1,0,1, or 2. |
| wait_bog disable -nowait_bog mode. |
| nowait_bog enable -nowait_bog mode. |
| slow_fb:f set -slow_fb to f seconds. |
| xrefresh:f set -xrefresh to f seconds. |
| readtimeout:n set read timeout to n seconds. |
| nap enable -nap mode. |
| nonap disable -nap mode. |
| sb:n set -sb to n s, same as screen_blank:n |
| fbpm disable -nofbpm mode. |
| nofbpm enable -nofbpm mode. |
| dpms disable -nodpms mode. |
| nodpms enable -nodpms mode. |
| forcedpms enable -forcedpms mode. |
| noforcedpms disable -forcedpms mode. |
| clientdpms enable -clientdpms mode. |
| noclientdpms disable -clientdpms mode. |
| noserverdpms enable -noserverdpms mode. |
| serverdpms disable -noserverdpms mode. |
| noultraext enable -noultraext mode. |
| ultraext disable -noultraext mode. |
| chatwindow enable local chatwindow mode. |
| nochatwindow disable local chatwindow mode. |
| chaton begin chat using local window. |
| chatoff end chat using local window. |
| xdamage enable xdamage polling hints. |
| noxdamage disable xdamage polling hints. |
| xd_area:A set -xd_area max pixel area to "A" |
| xd_mem:f set -xd_mem remembrance to "f" |
| fs:frac set -fs fraction to "frac", e.g. 0.5 |
| gaps:n set -gaps to n. |
| grow:n set -grow to n. |
| fuzz:n set -fuzz to n. |
| snapfb enable -snapfb mode. |
| nosnapfb disable -snapfb mode. |
| rawfb:str set -rawfb mode to "str". |
| uinput_accel:f set uinput_accel to f. |
| uinput_thresh:n set uinput_thresh to n. |
| uinput_reset:n set uinput_reset to n ms. |
| uinput_always:n set uinput_always to 1/0. |
| progressive:n set LibVNCServer -progressive slice |
| height parameter to n. |
| desktop:str set -desktop name to str for new clients |
| . |
| rfbport:n set -rfbport to n. |
| macnosaver enable -macnosaver mode. |
| macsaver disable -macnosaver mode. |
| macnowait enable -macnowait mode. |
| macwait disable -macnowait mode. |
| macwheel:n set -macwheel to n. |
| macnoswap enable -macnoswap mouse button mode. |
| macswap disable -macnoswap mouse button mode. |
| macnoresize enable -macnoresize mode. |
| macresize disable -macnoresize mode. |
| maciconanim:n set -maciconanim to n. |
| macmenu enable -macmenu mode. |
| macnomenu disable -macmenu mode. |
| macuskbd enable -macuskbd mode. |
| macnouskbd disable -macuskbd mode. |
| httpport:n set -httpport to n. |
| httpdir:dir set -httpdir to dir (and enable http). |
| enablehttpproxy enable -enablehttpproxy mode. |
| noenablehttpproxy disable -enablehttpproxy mode. |
| alwaysshared enable -alwaysshared mode. |
| noalwaysshared disable -alwaysshared mode. |
| (may interfere with other options) |
| nevershared enable -nevershared mode. |
| nonevershared disable -nevershared mode. |
| (may interfere with other options) |
| dontdisconnect enable -dontdisconnect mode. |
| nodontdisconnect disable -dontdisconnect mode. |
| (may interfere with other options) |
| debug_xevents enable debugging X events. |
| nodebug_xevents disable debugging X events. |
| debug_xdamage enable debugging X DAMAGE mechanism. |
| nodebug_xdamage disable debugging X DAMAGE mechanism. |
| debug_wireframe enable debugging wireframe mechanism. |
| nodebug_wireframe disable debugging wireframe mechanism. |
| debug_scroll enable debugging scrollcopy mechanism. |
| nodebug_scroll disable debugging scrollcopy mechanism. |
| debug_tiles enable -debug_tiles |
| nodebug_tiles disable -debug_tiles |
| debug_grabs enable -debug_grabs |
| nodebug_grabs disable -debug_grabs |
| debug_sel enable -debug_sel |
| nodebug_sel disable -debug_sel |
| debug_ncache enable -debug_ncache |
| nodebug_ncache disable -debug_ncache |
| dbg enable -dbg crash shell |
| nodbg disable -dbg crash shell |
| |
| noremote disable the -remote command processing, |
| it cannot be turned back on. |
| |
| bcx_xattach:str This remote control command is for |
| use with the BARCO xattach program or the x2x program. |
| Both of these programs are for 'pointer and keyboard' |
| sharing between separate X displays. In general the |
| two displays are usually nearby, e.g. on the same desk, |
| and this allows the user to share a single pointer and |
| keyboard between them. The user moves the mouse to |
| an edge and then the mouse pointer appears to 'jump' |
| to the other display screen. Thus it emulates what a |
| single X server would do for two screens (e.g. :0.0 and |
| :0.1) The illusion of a single Xserver with multiple |
| screens is achieved by forwarding events to the 2nd |
| one via the XTEST extension. |
| |
| What the x11vnc bcx_xattach command does is to perform |
| some pointer movements to try to INDUCE xattach/x2x |
| to 'jump' to the other display. In what follows the |
| 'master' display refers to the one that when it has |
| 'focus' it is basically doing nothing besides watching |
| for the mouse to go over an edge. The 'slave' |
| display refers to the one to which the mouse and |
| keyboard is redirected to once an edge in the master |
| has been crossed. Note that the x11vnc executing the |
| bcx_xattach command MUST be the one connected to the |
| *master* display. |
| |
| Also note that when input is being redirected (via |
| XTEST) from the master display to the slave display, |
| the master display's pointer and keyboard are *grabbed* |
| by xattach/x2x. x11vnc can use this info to verify that |
| the master/slave mode change has taken place correctly. |
| If you specify the "ifneeded" option (see below) |
| and the initial grab state is that of the desired |
| final state, then no pointer movements are injected |
| and "DONE,GRAB_OK" is returned. |
| |
| "str" must contain one of "up", "down", "left", |
| or "right" to indicate the direction of the 'jump'. |
| "str" must also contain one of "master_to_slave" |
| or "slave_to_master" to indicate the type of mode |
| change induced by the jump. Use "M2S" and "S2M" |
| as shorter aliases. |
| |
| "str" may be a "+" separated list of additional |
| tuning options. The "shift=n" option indicates an |
| offset shift position away from (0,0) (default 20). |
| "final=x+y" specifies the final position of the cursor |
| at the end of the normal move sequence; default 30+30. |
| "extra_move=x+y" means to do one more pointer move |
| after "final" to x+y. "dt=n" sets the sleep time |
| in milliseconds between pointer moves (default: 40ms) |
| "retry=n" specifies the maximum number of retries if |
| the grab state change fails. "ifneeded" means to not |
| apply the pointer movements if the initial grab state is |
| that of the desired final state. "nograbcheck" means |
| to not check if the grab state changed as expected and |
| only apply the pointer movements (default is to check |
| the grab states.) |
| |
| If you do not specify "up", etc., to bcx_xattach |
| nothing will be attempted and the command returns |
| the string FAIL,NO_DIRECTION_SPECIFIED. If you do |
| not specify "master_to_slave" or "M2S", etc., to |
| bcx_xattach nothing will be attempted and the command |
| returns the string FAIL,NO_MODE_CHANGE_SPECIFIED. |
| |
| Otherwise, the returned string will contain "DONE". |
| It will be "DONE,GRAB_OK" if the grab state changed |
| as expected (or if "ifneeded" was supplied and |
| the initial grab state was already the desired |
| one.) If the initial grab state was incorrect, |
| but the final grab state was correct then it is |
| "DONE,GRAB_FAIL_INIT". If the initial grab state |
| was correct, but the final grab state was incorrect |
| then it is "DONE,GRAB_FAIL_FINAL". If both are |
| incorrect it will be "DONE,GRAB_FAIL". Under grab |
| failure the string will be followed by ":p1,k1-p2,k2" |
| where p1,k1 indicates the initial pointer and keyboard |
| grab states and p2,k2 the final ones. If GRAB_FAIL or |
| GRAB_FAIL_FINAL occurs, the action will be retried up |
| to 3 times; trying to reset the state and sleeping a |
| bit between each try. Set retry=n to adjust the number |
| of retries, zero to disable retries. |
| |
| Examples: |
| -R bcx_xattach:down+M2S |
| -R bcx_xattach:up+S2M |
| -R bcx_xattach:up+S2M+nograbcheck+dt=30 |
| -R bcx_xattach:down+M2S+extra_move=100+100 |
| |
| or use -Q instead of -R to retrieve the result text. |
| |
| End of the bcx_xattach:str description. |
| |
| The vncconnect(1) command from standard VNC |
| distributions may also be used if string is prefixed |
| with "cmd=" E.g. 'vncconnect cmd=stop'. Under some |
| circumstances xprop(1) can used if it supports -set |
| (see the FAQ). |
| |
| If "-connect /path/to/file" has been supplied to the |
| running x11vnc server then that file can be used as a |
| communication channel (this is the only way to remote |
| control one of many x11vnc's polling the same X display) |
| Simply run: 'x11vnc -connect /path/to/file -remote ...' |
| or you can directly write to the file via something |
| like: "echo cmd=stop > /path/to/file", etc. |
| |
| -query variable Like -remote, except just query the value of |
| "variable". "-Q" is an alias for "-query". |
| Multiple queries can be done by separating variables |
| by commas, e.g. -query var1,var2. The results come |
| back in the form ans=var1:value1,ans=var2:value2,... |
| to the standard output. If a variable is read-only, |
| it comes back with prefix "aro=" instead of "ans=". |
| |
| Some -remote commands are pure actions that do not make |
| sense as variables, e.g. "stop" or "disconnect", in |
| these cases the value returned is "N/A". To direct a |
| query straight to the X11VNC_REMOTE property or connect |
| file use "qry=..." instead of "cmd=..." |
| |
| ans= stop quit exit shutdown ping resend_cutbuffer |
| resend_clipboard resend_primary blacken zero refresh |
| reset close disconnect id_cmd id sid waitmapped |
| nowaitmapped clip flashcmap noflashcmap shiftcmap |
| truecolor notruecolor overlay nooverlay overlay_cursor |
| overlay_yescursor nooverlay_nocursor nooverlay_cursor |
| nooverlay_yescursor overlay_nocursor 8to24 no8to24 |
| 8to24_opts 24to32 no24to32 visual scale scale_cursor |
| viewonly noviewonly shared noshared forever noforever |
| once timeout tightfilexfer notightfilexfer ultrafilexfer |
| noultrafilexfer rfbversion deny lock nodeny unlock avahi |
| mdns zeroconf noavahi nomdns nozeroconf connect proxy |
| allowonce allow noipv6 ipv6 noipv4 ipv4 no6 6 localhost |
| nolocalhost listen lookup nolookup accept afteraccept |
| gone shm noshm flipbyteorder noflipbyteorder onetile |
| noonetile solid_color solid nosolid blackout xinerama |
| noxinerama xtrap noxtrap xrandr noxrandr xrandr_mode |
| rotate padgeom quiet q noquiet modtweak nomodtweak xkb |
| noxkb capslock nocapslock skip_lockkeys noskip_lockkeys |
| skip_keycodes sloppy_keys nosloppy_keys skip_dups |
| noskip_dups add_keysyms noadd_keysyms clear_mods |
| noclear_mods clear_keys noclear_keys clear_all |
| clear_locks keystate remap repeat norepeat fb nofb bell |
| nobell sendbell sel nosel primary noprimary setprimary |
| nosetprimary clipboard noclipboard setclipboard |
| nosetclipboard seldir cursorshape nocursorshape |
| cursorpos nocursorpos cursor_drag nocursor_drag cursor |
| show_cursor noshow_cursor nocursor arrow xfixes noxfixes |
| xdamage noxdamage xd_area xd_mem alphacut alphafrac |
| alpharemove noalpharemove alphablend noalphablend |
| xwarppointer xwarp noxwarppointer noxwarp always_inject |
| noalways_inject buttonmap dragging nodragging ncache_cr |
| noncache_cr ncache_no_moveraise noncache_no_moveraise |
| ncache_no_dtchange noncache_no_dtchange |
| ncache_no_rootpixmap noncache_no_rootpixmap |
| ncache_reset_rootpixmap ncrp ncache_keep_anims |
| noncache_keep_anims ncache_old_wm noncache_old_wm |
| ncache_pad ncache noncache ncache_size debug_ncache |
| nodebug_ncache wireframe_mode wireframe wf nowireframe |
| nowf wireframelocal wfl nowireframelocal nowfl |
| wirecopyrect wcr nowirecopyrect nowcr scr_area |
| scr_skip scr_inc scr_keys scr_term scr_keyrepeat |
| scr_parms scrollcopyrect scr noscrollcopyrect |
| noscr fixscreen noxrecord xrecord reset_record |
| pointer_mode pm input_skip allinput noallinput |
| input_eagerly noinput_eagerly input grabkbd nograbkbd |
| grabptr nograbptr grabalways nograbalways grablocal |
| client_input ssltimeout speeds wmdt debug_pointer dp |
| nodebug_pointer nodp debug_keyboard dk nodebug_keyboard |
| nodk keycode keysym ptr fakebuttonevent sleep get_xprop |
| set_xprop wininfo bcx_xattach deferupdate defer |
| setdefer extra_fbur wait_ui wait_bog nowait_bog |
| slow_fb xrefresh wait readtimeout nap nonap sb |
| screen_blank fbpm nofbpm dpms nodpms clientdpms |
| noclientdpms forcedpms noforcedpms noserverdpms |
| serverdpms noultraext ultraext chatwindow nochatwindow |
| chaton chatoff fs gaps grow fuzz snapfb nosnapfb |
| rawfb uinput_accel uinput_thresh uinput_reset |
| uinput_always progressive rfbport http nohttp httpport |
| httpdir enablehttpproxy noenablehttpproxy alwaysshared |
| noalwaysshared nevershared noalwaysshared dontdisconnect |
| nodontdisconnect desktop debug_xevents nodebug_xevents |
| debug_xevents debug_xdamage nodebug_xdamage |
| debug_xdamage debug_wireframe nodebug_wireframe |
| debug_wireframe debug_scroll nodebug_scroll debug_scroll |
| debug_tiles dbt nodebug_tiles nodbt debug_tiles |
| debug_grabs nodebug_grabs debug_sel nodebug_sel dbg |
| nodbg macnosaver macsaver nomacnosaver macnowait macwait |
| nomacnowait macwheel macnoswap macswap nomacnoswap |
| macnoresize macresize nomacnoresize maciconanim macmenu |
| macnomenu nomacmenu macuskbd nomacuskbd noremote |
| |
| aro= noop display vncdisplay icon_mode autoport |
| loop loopbg desktopname guess_desktop guess_dbus |
| http_url auth xauth users rootshift clipshift scale_str |
| scaled_x scaled_y scale_numer scale_denom scale_fac_x |
| scale_fac_y scaling_blend scaling_nomult4 scaling_pad |
| scaling_interpolate inetd privremote unsafe safer nocmds |
| passwdfile unixpw unixpw_nis unixpw_list ssl ssl_pem |
| sslverify stunnel stunnel_pem https httpsredir usepw |
| using_shm logfile o flag rmflag rc norc h help V version |
| lastmod bg sigpipe threads readrate netrate netlatency |
| pipeinput clients client_count pid ext_xtest ext_xtrap |
| ext_xrecord ext_xkb ext_xshm ext_xinerama ext_overlay |
| ext_xfixes ext_xdamage ext_xrandr rootwin num_buttons |
| button_mask mouse_x mouse_y grab_state pointer_pos |
| pointer_x pointer_y pointer_same pointer_root |
| pointer_mask bpp depth indexed_color dpy_x dpy_y wdpy_x |
| wdpy_y off_x off_y cdpy_x cdpy_y coff_x coff_y rfbauth |
| passwd viewpasswd |
| |
| -QD variable Just like -query variable, but returns the default |
| value for that parameter (no running x11vnc server |
| is consulted) |
| |
| -sync By default -remote commands are run asynchronously, that |
| is, the request is posted and the program immediately |
| exits. Use -sync to have the program wait for an |
| acknowledgement from the x11vnc server that command was |
| processed (somehow). On the other hand -query requests |
| are always processed synchronously because they have |
| to wait for the answer. |
| |
| Also note that if both -remote and -query requests are |
| supplied on the command line, the -remote is processed |
| first (synchronously: no need for -sync), and then |
| the -query request is processed in the normal way. |
| This allows for a reliable way to see if the -remote |
| command was processed by querying for any new settings. |
| Note however that there is timeout of a few seconds |
| (see the next paragraph) so if the x11vnc takes longer |
| than that to process the requests the requester will |
| think that a failure has taken place. |
| |
| The default is to wait 3.5 seconds. Or if cmd=stop |
| only 1.0 seconds. If cmd matches 'script:' then it |
| will wait up to 10.0 seconds. Set X11VNC_SYNC_TIMEOUT |
| to the number of seconds you want it to wait. |
| |
| -query_retries str If a query fails to get a response from an x11vnc |
| server, retry up to n times. "str" is specified as |
| n[:t][/match] Optionally the delay between tries may |
| be specified by "t" a floating point time (default |
| 0.5 seconds.) Note: the response is not checked for |
| validity or whether it corresponds to the query sent. |
| The query "ping:mystring" may be used to help uniquely |
| identify the query. Optionally, a matching string after |
| a "/" will be used to check the result text. Up to |
| n retries will take place until the matching string is |
| found in the output text. If the match string is never |
| found the program's exit code is 1; if the match is |
| found it exits with 0. Note that there may be stdout |
| printed for each retry (i.e. multiple lines printed |
| out to stdout.) |
| Example: -query_retries 4:1.5/grab_state |
| |
| -remote_prefix str Enable a remote-control communication channel for |
| connected VNC clients. str is a non-empty string. If a |
| VNC client sends rfbCutText having the prefix "str" |
| then the part after it is processed as though it were |
| sent via 'x11vnc -remote ...'. If it begins with |
| neither 'cmd=' nor 'qry=' then 'qry=' is assumed. |
| Any corresponding output text for that remote control |
| command is sent back to all client as rfbCutText. |
| The returned output is also prefixed with "str". |
| Example: -remote_prefix DO_THIS: |
| |
| Note that enabling -remote_prefix allows the remote |
| VNC viewers to run x11vnc -remote commands. Do not |
| use this option if they are not to be trusted. |
| |
| -noremote Do not process any remote control commands or queries. |
| -yesremote Do process remote control commands or queries. |
| Default: -yesremote |
| |
| A note about security wrt remote control commands. |
| If someone can connect to the X display and change |
| the property X11VNC_REMOTE, then they can remotely |
| control x11vnc. Normally access to the X display is |
| protected. Note that if they can modify X11VNC_REMOTE |
| on the X server, they have enough permissions to also |
| run their own x11vnc and thus have complete control |
| of the desktop. If the "-connect /path/to/file" |
| channel is being used, obviously anyone who can write |
| to /path/to/file can remotely control x11vnc. So be |
| sure to protect the X display and that file's write |
| permissions. See -privremote below. |
| |
| If you are paranoid and do not think -noremote is |
| enough, to disable the X11VNC_REMOTE property channel |
| completely use -novncconnect, or use the -safer option |
| that shuts many things off. |
| |
| -unsafe A few remote commands are disabled by default |
| (currently: id:pick, accept:<cmd>, gone:<cmd>, and |
| rawfb:setup:<cmd>) because they are associated with |
| running external programs. If you specify -unsafe, then |
| these remote-control commands are allowed. Note that |
| you can still specify these parameters on the command |
| line, they just cannot be invoked via remote-control. |
| -safer Equivalent to: -novncconnect -noremote and prohibiting |
| -gui and the -connect file. Shuts off communcation |
| channels. |
| -privremote Perform some sanity checks and disable remote-control |
| commands if it appears that the X DISPLAY and/or |
| connectfile can be accessed by other users. Once |
| remote-control is disabled it cannot be turned back on. |
| -nocmds No external commands (e.g. system(3), popen(3), exec(3)) |
| will be run at all. |
| -allowedcmds list "list" contains a comma separated list of the only |
| external commands that can be run. The full list of |
| associated options is: |
| |
| stunnel, ssl, unixpw, WAIT, zeroconf, id, accept, |
| afteraccept, gone, pipeinput, v4l-info, rawfb-setup, |
| dt, gui, ssh, storepasswd, passwdfile, custom_passwd, |
| findauth, crash. |
| |
| See each option's help to learn the associated external |
| command. Note that the -nocmds option takes precedence |
| and disables all external commands. |
| |
| -deny_all For use with -remote nodeny: start out denying all |
| incoming clients until "-remote nodeny" is used to |
| let them in. |
| |
| |
| |
| These options are passed to LibVNCServer: |
| |
| -rfbport port TCP port for RFB protocol |
| -rfbwait time max time in ms to wait for RFB client |
| -rfbauth passwd-file use authentication on RFB protocol |
| (use 'storepasswd' to create a password file) |
| -rfbversion 3.x Set the version of the RFB we choose to advertise |
| -permitfiletransfer permit file transfer support |
| -passwd plain-password use authentication |
| (use plain-password as password, USE AT YOUR RISK) |
| -deferupdate time time in ms to defer updates (default 40) |
| -deferptrupdate time time in ms to defer pointer updates (default none) |
| -desktop name VNC desktop name (default "LibVNCServer") |
| -alwaysshared always treat new clients as shared |
| -nevershared never treat new clients as shared |
| -dontdisconnect don't disconnect existing clients when a new non-shared |
| connection comes in (refuse new connection instead) |
| -httpdir dir-path enable http server using dir-path home |
| -httpport portnum use portnum for http connection |
| -enablehttpproxy enable http proxy support |
| -progressive height enable progressive updating for slow links |
| -listen ipaddr listen for connections only on network interface with |
| addr ipaddr. '-listen localhost' and hostname work too. |
| |
| libvncserver-tight-extension options: |
| -disablefiletransfer disable file transfer |
| -ftproot string set ftp root |
| |
| Pretty wild huh? Contact me if you have any questions or problems. |
| |
| Personally, I use: |
| x11vnc -rfbauth $HOME/.vnc/passwd -solid |