X11VNC(1) User Commands X11VNC(1) NAME x11vnc - allow VNC connections to real X11 displays version: 0.9.13, lastmod: 2011-08-10 SYNOPSIS x11vnc [OPTION]... DESCRIPTION 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 lis‐ tening 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 recom‐ mended. 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 lis‐ tening 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 sup‐ port. -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 con‐ nections 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 con‐ necting.) You can disable this by setting X11VNC_AVOID_WIN‐ DOWS=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 dis‐ play. New windows like popup menus, transient toplevels, etc, may not be seen or may be clipped. Disabling SaveUnders or Backing‐ Store in the X server may help show them. x11vnc may crash if the window is initially partially obscured, changes size, is iconi‐ fied, 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. -tag str This option is ignored, but allows you to specify a unique string on the x11vnc command line, for example "-tag test34934z", this could enable a reliable way to identify different x11vnc processes via their command lines (see ps(1) , pgrep(1) , and pkill(1) and /proc/PID/cmdline.) -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 xin‐ erama 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 dou‐ ble 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 XGetIm‐ age 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 Pseu‐ doColor 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 dis‐ play 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 frame‐ buffer. 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 min‐ imize 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 True‐ Color: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: -never‐ shared -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 listen‐ ing 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. If the libvncserver used supports non AF_INET sockets (the one bundled in x11vnc 0.9.13 and later does), then -inetd mode can be used for a raw stdio pipe. For example, using the SSVNC viewer exec=... mechanism: ssvnc -viewer exec="ssh -tt -e none user@host \ ´x11vnc -inetd -o log.txt -display :0'" where the long cmdline has been split. In the above the only TCP connection is that of the ssh connection. There is no port redi‐ rection (-L), etc.; raw stdio is used on both sides of the ssh. In some cases the -tt option is not needed. -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 file‐ transfer 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 file‐ transfer reads and writes as *root*. Note that sadly you cannot do both -tightfilexfer and -ultra‐ filexfer 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 direc‐ tory is by looking relative to the program location and in stan‐ dard 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 pass‐ word auth has been enabled, -rfbauth, etc) If you do not want to require a password for reverse connections set X11VNC_REVERSE_CON‐ NECTION_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=<IP_ADDRESS>::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 sup‐ plied 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 car‐ riage 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 connect‐ ing, 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 dis‐ cussed 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 suc‐ ceed, 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", other‐ wise 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 con‐ nect host and port. Use the string "__END__" to disable the appending. The basic idea here is that maybe some cgi script pro‐ vides 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-stan‐ dard 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 ric‐ ochet 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,sec‐ ond,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, -novncconnect Monitor the VNC_CONNECT X property set by the standard VNC program vncconnect(1). When the property is set to "host" or "host:port" establish a reverse connection. Using xprop(1) instead of vnc‐ connect 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 sep‐ arate 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 sepa‐ rated list of hostnames or IP addresses. By ending in a ".", it 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 numeri‐ cal format, e.g. 2001:4860:b009::93 Env. vars: Set -env X11VNC_DEBUG_ACCESS=1 to print out debugging info during the check_access() call. Set -env X11VNC_ALLOW_FULL‐ MATCH=1 to force a full string match, that is, no subnet "." matching will be performed. Unix sockets: if -unixsock is being used and you want to limit TCP access also you must also include the path to the unix socket pre‐ fixed with "unix=" in the allow list, e.g.: -allow <IP_ADDRESS>,unix=/tmp/mysock If the socket is not a named one, e.g. created via socketpair(2) with -inetd, then you must supply the generic name x11vnc gives to it, e.g. -allow <IP_ADDRESS>,UNNAMED_AF_UNIX In both cases it must be an exact string match to be allowed to connect. Note that since you com‐ pletely control these local non-TCP access methods by file system permissions, etc., it is not useful to guard against them with -allow, however you still need to have them in the allow list to let them connect. -localhost Basically the same as "-allow <IP_ADDRESS>". Note: if you want to restrict which network interface x11vnc lis‐ tens on, see the -listen option below. E.g. "-listen localhost" or "-listen <IP_ADDRESS>". As a special case, the option "-local‐ host" 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 TCP interface (evi‐ dently you are using -connect or -connect_or_exit, or plan to use remote control: -R connect:host, or to use -unixsock), specify -rfbport 0 IPv6: if IPv6 is supported, this option automatically implies the IPv6 loopback address '::1' as well. -unixsock str In addition to the regular TCP port, listen on the unix socket (AF_UNIX) 'str' for incoming 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. Example: mkdir ~/s; chmod 700 ~/s; x11vnc -unixsock ~/s/mysock -rfbport 0 ... same as: x11vnc -unixsockonly ~/s/mysock ... (see -unixsockonly below.) This mode currently requires the modified libvncserver bundled in the the x11vnc 0.9.13 tarball and later. Note that the SSVNC unix vncviewer can connect to unix sockets, for example: ssvnc -viewer unix=./s/mysock As a special mechanism, if 'str' for either -unixsock or -unix‐ sockonly is of the form "fd=n" where n is a non-negative decimal integer, then instead of creating a unix socket, that file descriptor (assumed already opened and O_RDWR) will be attached as a VNC client. Perhaps the program that execs x11vnc has created a socketpair(2) to communicate over. Use this mechanism if -inetd (which is basically fd=0) is not flexible enough for you. -unixsockonly str Listen on unix socket 'str' only, no TCP ports. First note that one can disable all tcp listening ports by specifying '-rfbport 0'. The option '-unixsockonly str' is functionally equivalent to '-unixsock str -rfbport 0' -listen6 str When in IPv6 listen mode "-6", listen only on the network inter‐ face 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 pres‐ ence 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 coopera‐ tion 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 win‐ dows 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 con‐ nected. If you only want one of them, use the -R remote control to turn the other back on, e.g. -R nograbptr. (PASSWORDS: Note that the LibVNCServer password options "-rfbauth file" and "-passwd str" are described at the bottom of the help output.) -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 authen‐ tication, 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 imme‐ diately. To specify more than 1000 passwords this way set X11VNC_MAX_PASSWDS before starting x11vnc. The environment vari‐ ables 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 pass‐ word 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 customiz‐ ing the VNC client as well. One could create an MD5SUM based scheme for example. See also -unixpw_cmd below. 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 anno‐ tated 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 compat‐ ibility, 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. -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; oth‐ erwise, 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 spe‐ cial cases described below. Be sure to quote string if it con‐ tains 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 implica‐ tions 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 identifica‐ tion 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 num‐ ber 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 success‐ fully 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 numeri‐ cal 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 unex‐ pected 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 &' -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 conserva‐ tive 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* pass‐ word 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 auto‐ matically 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 re‐ direction). 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 vari‐ ables 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 require‐ ment 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 con‐ nection 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 "+" sepa‐ rated 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. "%stdin2" means read the username from the first stdin line and the password from the seconde stdin line. "%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 cor‐ rect.) 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 tra‐ ditional 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 pass‐ word verifying function based on su called (i.e. the function su_verify() that runs /bin/su in a pseudoterminal to verify pass‐ words.) However, if -unixpw_nis is used in conjunction with the -find and -create -display WAIT:... modes then, if x11vnc is run‐ ning 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 imple‐ mented this way by providing your own custom helper program. Note that the remote viewer is given 3 tries to enter the correct pass‐ word, 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 exit 1 In -unixpw_cmd mode, under no circumstances is x11vnc's user pass‐ word verifying function based on su called (i.e. the function su_verify() that runs /bin/su in a pseudoterminal to verify pass‐ words.) It is up to the supplied unixpw_cmd to do user switching if desired and if it has the permissions to do so. See also "-passwdfile custom:..." above for a non unix username based custom password checking interface. -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 over‐ ride 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 $DIS‐ PLAY 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 "XAUTHOR‐ ITY=/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=FINDCREATEDIS‐ PLAY-Xvfb". Note: if a -display occurs later on the command line it will over‐ ride 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 discus‐ sion under -display WAIT:... for more details about XDM, etc con‐ figuration. 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 con‐ necting 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_sys‐ tem_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 ses‐ sion 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 immedi‐ ately (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 con‐ junction 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 ser‐ vice. -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 con‐ nects 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 FINDCREATE‐ DISPLAY (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 sup‐ ports 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 "fail‐ safe" (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 automati‐ cally 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 customiza‐ tion) 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 ses‐ sion 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_FINDDIS‐ PLAY_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 dis‐ plays are allowed (i.e. going to :99) Override via X11VNC_CRE‐ ATE_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_CRE‐ ATE_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 circum‐ stances 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_OUT‐ PUT=/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_FINDDIS‐ PLAY_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 pro‐ gram 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, -geome‐ try, and -depth and other X server options). You can set the environment variable FD_GEOM (or X11VNC_CRE‐ ATE_GEOM) to WxH or WxHxD to set the width and height and option‐ ally 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 man‐ agers. 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 man‐ ager. 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 back‐ ground once listening in wait mode. Another special mode is FINDCREATEDISPLAY-Xvnc.redirect, (or FIND‐ DISPLAY-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 "sup‐ port" (the default) then VeNCrypt is supported. If mode is "only", then the similar and older ANONTLS protocol is not simul‐ taneously 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 parame‐ ters are generated for each connection (this can be time consum‐ ing: 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 pro‐ tocol 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 "sup‐ port" (the default) then ANONTLS is supported. If mode is "only", then the similar VeNCrypt protocol is not simultaneously sup‐ ported. 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 parame‐ ters are generated for each connection (this can be time consum‐ ing: 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 par‐ ticular, 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 *ear‐ lier* -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 immedi‐ ately 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.karl‐ runge.com/x11vnc/faq.html#faq-ssl-tun nel-viewers . x11vnc pro‐ vides an SSL enabled Java viewer applet in the classes/ssl direc‐ tory (-http or -httpdir options.) The SSVNC viewer package sup‐ ports 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) authenti‐ cate 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. Oth‐ erwise, 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 gener‐ ated 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 cre‐ ated 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 gener‐ ated 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 tem‐ porary certificate x11vnc exits immediately. The temporary cert will be discarded when x11vnc exits. If successful in using openssl(1) to generate a temporary certifi‐ cate 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 sup‐ port, 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 con‐ nection 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 con‐ nection. 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 mul‐ tiple 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 cer‐ tificates to authenticate incoming VNC *Client* connections (nor‐ mally 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 stun‐ nel(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 direc‐ tory, 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 auto‐ matically 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 admin‐ istrator could generate a single CA key with -sslGenCA and dis‐ tribute 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 them‐ selves 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 for‐ mat. If path is a directory, it contains hash named files of CRLs in the usual OpenSSL manner. See the OpenSSL and stunnel(8) docu‐ mentation 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 -sslver‐ ify is not specified. Note that if a CRL's expiration date has passed, all SSL connec‐ tions 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 con‐ tents of the -sslverify file or directory should be enough.) How‐ ever, 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 dis‐ tributed 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 certifi‐ cate. 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 authen‐ ticate 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 certifi‐ cate 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 infor‐ mation that will be recorded in the certificate when it is cre‐ ated. 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 -dis‐ play :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 sup‐ ply 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 avail‐ able 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 con‐ catenate 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 lower‐ case, 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 -sslCert‐ Info 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 inte‐ grated -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 direc‐ tories). 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 sup‐ ported 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 rout‐ ing 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 inter‐ face to listen on (the default is to listen on all interfaces), e.g. STUNNEL_LISTEN=<IP_ADDRESS>. 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 exam‐ ples. -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 key‐ file 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=sword‐ fish 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 (with‐ out 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, key‐ data, 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' (or replace 'ssvncviewer' with 'ssvnc -viewer') 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 reli‐ able HTTPS port that x11vnc will listen on. If [port] is not pro‐ vided (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 per‐ formed 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://mygate‐ way.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 hav‐ ing to include the PORT= in the browser URL, simply supply "-http‐ sredir" 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_LIS‐ TEN_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 Lib‐ VNCServer 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, -stun‐ nel, 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 con‐ nections 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; view‐ ers can reach it more easily. "disp" is the VNC display for the remote SSH side, e.g. 0 corre‐ sponds 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. -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 run‐ ning 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 par‐ ticular under GNOME and KDE to implement the "-solid color" fea‐ ture 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 pro‐ cesses 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 dis‐ play can still be successfully opened as that user (this is pri‐ marily to try to guess the actual owner of the session). Example: "-users fred,wilma,betty". Note that a malicious local user "bar‐ ney" 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 immedi‐ ately regardless if the display can be reopened prefix the user‐ name 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 (pri‐ mary 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 list 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 sup‐ plied. 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<EMAIL_ADDRESS>of the "Sub‐ ject" 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 sepa‐ rated 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 dis‐ play 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 con‐ nects 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 indi‐ cates 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. Exam‐ ples: "-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 spec‐ ify 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 pre‐ fixing 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, -noxinerama If your screen is composed of multiple monitors 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 inser‐ tion. For use on legacy systems, e.g. X11R5, running an incom‐ plete 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 Reflec‐ tion) extension, and you expect XRANDR events to occur to the dis‐ play 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 encod‐ ing, since it knows how to react to screen size changes. Other‐ wise, 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. "newf‐ bsize" 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 orig‐ inal 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 pre‐ fixed 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 use‐ ful 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, -nomodtweak Option -modtweak automatically tries to adjust the AltGr 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 MOD‐ TWEAK_LOWEST=1 to see if it helps. -xkb, -noxkb When in modtweak mode, use the XKEYBOARD extension (if the X dis‐ play 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 mod