x11vnc: allow VNC connections to real X11 displays. 0.9.17 lastmod: 2025-04-11 (type "x11vnc -opts" to just list the options.) Typical usage is: Run this command in a shell on the remote machine "far-host" with X session you wish to view: x11vnc -display :0 Then run this in another window on the machine you are sitting at: vncviewer far-host:0 Once x11vnc establishes connections with the X11 server and starts listening as a VNC server it will print out a string: PORT=XXXX where XXXX is typically 5900 (the default VNC server port). One would next run something like this on the local machine: "vncviewer hostname:N" where "hostname" is the name of the machine running x11vnc and N is XXXX - 5900, i.e. usually "vncviewer hostname:0". By default x11vnc will not allow the screen to be shared and it will exit as soon as the client disconnects. See -shared and -forever below to override these protections. See the FAQ for details how to tunnel the VNC connection through an encrypted channel such as ssh(1). In brief: ssh -t -L 5900:localhost:5900 far-host 'x11vnc -localhost -display :0' vncviewer -encodings 'copyrect tight zrle hextile' localhost:0 Also, use of a VNC password (-rfbauth or -passwdfile) is strongly recommended. For additional info see: http://www.karlrunge.com/x11vnc/ and http://www.karlrunge.com/x11vnc/faq.html Config file support: if the file $HOME/.x11vncrc exists then each line in it is treated as a single command line option. Disable with -norc. For each option name, the leading character "-" is not required. E.g. a line that is either "forever" or "-forever" may be used and are equivalent. Likewise "wait 100" or "-wait 100" are acceptable and equivalent lines. The "#" character comments out to the end of the line in the usual way (backslash it for a literal). Leading and trailing whitespace is trimmed off. Lines may be continued with a "\" as the last character of a line (it becomes a space character). Options: -display disp X11 server display to connect to, usually :0. The X server process must be running on same machine and support MIT-SHM. Equivalent to setting the DISPLAY environment variable to "disp". See the description below of the "-display WAIT:..." extensions, where alias "-find" will find the user's display automatically, and "-create" will create a Xvfb session if no session is found. -auth file Set the X authority file to be "file", equivalent to setting the XAUTHORITY environment variable to "file" before startup. Same as -xauth file. See Xsecurity(7), xauth(1) man pages for more info. Use '-auth guess' to have x11vnc use its -findauth mechanism (described below) to try to guess the XAUTHORITY filename and use it. XDM/GDM/KDM: if you are running x11vnc as root and want to find the XAUTHORITY before anyone has logged into an X session yet, use: x11vnc -env FD_XDM=1 -auth guess ... (This will also find the XAUTHORITY if a user is already logged into the X session.) When running as root, FD_XDM=1 will be tried if the initial -auth guess fails. -N If the X display is :N, try to set the VNC display to also be :N This just sets the -rfbport option to 5900+N The program will exit immediately if that port is not available. The -N option only works with normal -display usage, e.g. :0 or :8, -N is ignored in the -display WAIT:..., -create, -find, -svc, -redirect, etc modes. -autoport n Automatically probe for a free VNC port starting at n. The default is to start probing at 5900. Use this to stay away from other VNC servers near 5900. -rfbport str The VNC port to listen on (a LibVNCServer option), e.g. 5900, 5901, etc. If specified as "-rfbport PROMPT" then the x11vnc -gui is used to prompt the user to enter the port number. -6 IPv6 listening support. In addition to IPv4, the IPv6 address is listened on for incoming connections. The same port number as IPv4 is used. NOTE: This x11vnc binary was compiled to have the "-6" IPv6 listening mode ENABLED by default (CPPFLAGS -DX11VNC_LISTEN6=1). So to disable IPv6 listening mode you MUST supply the "-no6" option (see below.) The "-6" mode works for both normal connections and -ssl encrypted ones. Nearly everything is supported for the IPv6 case, but there are a few exceptions. See -stunnel for its IPv6 support. Currently, for absolutely everything to work correctly the machine may need to have some IPv4 support, at the least for the loopback interface. However, for nearly all usage modes no IPv4 support is required. See -noipv4. If you have trouble compiling or running in IPv6 mode, set -DX11VNC_IPV6=0 in CPPFLAGS when configuring to disable IPv6 support. -no6 Disable IPv6 listening support (only useful if the "-6" mode is compiled in to be the default; see the X11VNC_LISTEN6 description above under "-6".) -noipv6 Do not try to use IPv6 for any listening or connecting sockets. This includes both the listening service port(s) and outgoing connections from -connect, -connect_or_exit, or -proxy. Use this if you are having problems due to IPv6. -noipv4 Do not try to use IPv4 for any listening or connecting sockets. This is mainly for exploring the behavior of x11vnc on an IPv6-only system, but may have other uses. -reopen If the X server connection is disconnected, try to reopen the X display (up to one time.) This is of use for display managers like GDM (KillInitClients option) that kill x11vnc just after the user logs into the X session. Note: the reopened state may be unstable. Set X11VNC_REOPEN_DISPLAY=n to reopen n times and set X11VNC_REOPEN_SLEEP_MAX to the number of seconds, default 10, to keep trying to reopen the display (once per second.) Update: as of 0.9.9, x11vnc tries to automatically avoid being killed by the display manager by delaying creating windows or using XFIXES. So you shouldn't need to use KillInitClients=false as long as you log in quickly enough (within 45 seconds of connecting.) You can disable this by setting X11VNC_AVOID_WINDOWS=never. You can also set it to the number of seconds to delay. -reflect host:N Instead of connecting to and polling an X display, connect to the remote VNC server host:N and be a reflector/repeater for it. This is useful for trying to manage the case of many simultaneous VNC viewers (e.g. classroom broadcasting) where, e.g. you put a repeater on each network switch, etc, to improve performance by distributing the load and network traffic. Implies -shared (use -noshared as a later option to disable). See the discussion below under -rawfb vnc:host:N for more details. -id windowid Show the X window corresponding to "windowid" not the entire display. New windows like popup menus, transient toplevels, etc, may not be seen or may be clipped. Disabling SaveUnders or BackingStore in the X server may help show them. x11vnc may crash if the window is initially partially obscured, changes size, is iconified, etc. Some steps are taken to avoid this and the -xrandr mechanism is used to track resizes. Use xwininfo(1) to get the window id, or use "-id pick" to have x11vnc run xwininfo(1) for you and extract the id. The -id option is useful for exporting very simple applications (e.g. the current view on a webcam). -sid windowid As -id, but instead of using the window directly it shifts a root view to it: this shows SaveUnders menus, etc, although they will be clipped if they extend beyond the window. -appshare Simple application sharing based on the -id/-sid mechanism. Every new toplevel window that the application creates induces a new viewer window via a reverse connection. The -id/-sid and -connect options are required. Run 'x11vnc -appshare -help' for more info. -clip WxH+X+Y Only show the sub-region of the full display that corresponds to the rectangle geometry with size WxH and offset +X+Y. The VNC display has size WxH (i.e. smaller than the full display). This also works for -id/-sid mode where the offset is relative to the upper left corner of the selected window. An example use of this option would be to split a large (e.g. Xinerama) display into two parts to be accessed via separate viewers by running a separate x11vnc on each part. Use '-clip xinerama0' to clip to the first xinerama sub-screen (if xinerama is active). xinerama1 for the 2nd sub-screen, etc. This way you don't need to figure out the WxH+X+Y of the desired xinerama sub-screen. screens are sorted in increasing distance from the (0,0) origin (I.e. not the Xserver's order). -flashcmap In 8bpp indexed color, let the installed colormap flash as the pointer moves from window to window (slow). Also try the -8to24 option to avoid flash altogether. -shiftcmap n Rare problem, but some 8bpp displays use less than 256 colorcells (e.g. 16-color grayscale, perhaps the other bits are used for double buffering) *and* also need to shift the pixels values away from 0, .., ncells. "n" indicates the shift to be applied to the pixel values. To see the pixel values set DEBUG_CMAP=1 to print out a colormap histogram. Example: -shiftcmap 240 -notruecolor For 8bpp displays, force indexed color (i.e. a colormap) even if it looks like 8bpp TrueColor (rare problem). -advertise_truecolor If the X11 display is indexed color, lie to clients when they first connect by telling them it is truecolor. To workaround RealVNC: inPF has colourMap but not 8bpp Use '-advertise_truecolor reset' to reset client fb too. -visual n This option probably does not do what you think. It simply *forces* the visual used for the framebuffer; this may be a bad thing... (e.g. messes up colors or cause a crash). It is useful for testing and for some workarounds. n may be a decimal number, or 0x hex. Run xdpyinfo(1) for the values. One may also use "TrueColor", etc. see for a list. If the string ends in ":m" then for better or for worse the visual depth is forced to be m. You may want to use -noshm when using this option (so XGetImage may automatically translate the pixel data). -overlay Handle multiple depth visuals on one screen, e.g. 8+24 and 24+8 overlay visuals (the 32 bits per pixel are packed with 8 for PseudoColor and 24 for TrueColor). Currently -overlay only works on Solaris via XReadScreen(3X11) and IRIX using XReadDisplay(3). On Solaris there is a problem with image "bleeding" around transient popup menus (but not for the menu itself): a workaround is to disable SaveUnders by passing the "-su" argument to Xsun (in /etc/dt/config/Xservers). Use -overlay as a workaround for situations like these: Some legacy applications require the default visual to be 8bpp (8+24), or they will use 8bpp PseudoColor even when the default visual is depth 24 TrueColor (24+8). In these cases colors in some windows will be incorrect in x11vnc unless -overlay is used. Another use of -overlay is to enable showing the exact mouse cursor shape (details below). Under -overlay, performance will be somewhat slower due to the extra image transformations required. For optimal performance do not use -overlay, but rather configure the X server so that the default visual is depth 24 TrueColor and try to have all apps use that visual (e.g. some apps have -use24 or -visual options). -overlay_nocursor Sets -overlay, but does not try to draw the exact mouse cursor shape using the overlay mechanism. -8to24 [opts] Try this option if -overlay is not supported on your OS, and you have a legacy 8bpp app that you want to view on a multi-depth display with default depth 24 (and is 32 bpp) OR have a default depth 8 display with depth 24 overlay windows for some apps. This option may not work on all X servers and hardware (tested on XFree86/Xorg mga driver and Xsun). The "opts" string is not required and is described below. This mode enables a hack where x11vnc monitors windows within 3 levels from the root window. If it finds any that are 8bpp it extracts the indexed color pixel values using XGetImage() and then applies a transformation using the colormap(s) to create TrueColor RGB values that it in turn inserts into bits 1-24 of the framebuffer. This creates a depth 24 "view" of the display that is then exported via VNC. Conversely, for default depth 8 displays, the depth 24 regions are read by XGetImage() and everything is transformed and inserted into a depth 24 TrueColor framebuffer. Note that even if there are *no* depth 24 visuals or windows (i.e. pure 8bpp), this mode is potentially an improvement over -flashcmap because it avoids the flashing and shows each window in the correct color. This method works OK, but may still have bugs and it does hog resources. If there are multiple 8bpp windows using different colormaps, one may have to iconify all but one for the colors to be correct. There may be painting errors for clipping and switching between windows of depths 8 and 24. Heuristics are applied to try to minimize the painting errors. One can also press 3 Alt_L's in a row to refresh the screen if the error does not repair itself. Also the option -fixscreen 8=3.0 or -fixscreen V=3.0 may be used to periodically refresh the screen at the cost of bandwidth (every 3 sec for this example). The [opts] string can contain the following settings. Multiple settings are separated by commas. For for some X servers with default depth 24 a speedup may be achieved via the option "nogetimage". This enables a scheme were XGetImage() is not used to retrieve the 8bpp data. Instead, it assumes that the 8bpp data is in bits 25-32 of the 32bit X pixels. There is no requirement that the X server should put the data there for our poll requests, but some do and so the extra steps to retrieve it can be skipped. Tested with mga driver with XFree86/Xorg. For the default depth 8 case this option is ignored. To adjust how often XGetImage() is used to poll the non-default visual regions for changes, use the option "poll=t" where "t" is a floating point time. (default: 0.05) Setting the option "level2" will limit the search for non-default visual windows to two levels from the root window. Do this on slow machines where you know the window manager only imposes one extra window between the app window and the root window. Also for very slow machines use "cachewin=t" where t is a floating point amount of time to cache XGetWindowAttributes results. E.g. cachewin=5.0. This may lead to the windows being unnoticed for this amount of time when deiconifying, painting errors, etc. While testing on a very old SS20 these options gave tolerable response: -8to24 poll=0.2,cachewin=5.0. For this machine -overlay is supported and gives better response. Debugging for this mode can be enabled by setting "dbg=1", "dbg=2", or "dbg=3". -24to32 Very rare problem: if the framebuffer (X display or -rawfb) is 24bpp instead of the usual 32bpp, then dynamically transform the pixels to 32bpp. This will be slower, but can be used to work around problems where VNC viewers cannot handle 24bpp (e.g. "main: setPF: not 8, 16 or 32 bpp?"). See the FAQ for more info. In the case of -rawfb mode, the pixels are directly modified by inserting a 0 byte to pad them out to 32bpp. For X displays, a kludge is done that is equivalent to "-noshm -visual TrueColor:32". (If better performance is needed for the latter, feel free to ask). -scale fraction Scale the framebuffer by factor "fraction". Values less than 1 shrink the fb, larger ones expand it. Note: the image may not be sharp and response may be slower. If "fraction" contains a decimal point "." it is taken as a floating point number, alternatively the notation "m/n" may be used to denote fractions exactly, e.g. -scale 2/3 To scale asymmetrically in the horizontal and vertical directions, specify a WxH geometry to stretch to: e.g. '-scale 1024x768', or also '-scale 0.9x0.75' Scaling Options: can be added after "fraction" via ":", to supply multiple ":" options use commas. If you just want a quick, rough scaling without blending, append ":nb" to "fraction" (e.g. -scale 1/3:nb). No blending is the default for 8bpp indexed color, to force blending for this case use ":fb". To disable -scrollcopyrect and -wirecopyrect under -scale use ":nocr". If you need to to enable them use ":cr" or specify them explicitly on the command line. If a slow link is detected, ":nocr" may be applied automatically. Default: :cr More esoteric options: for compatibility with vncviewers the scaled width is adjusted to be a multiple of 4: to disable this use ":n4". ":in" use interpolation scheme even when shrinking, ":pad" pad scaled width and height to be multiples of scaling denominator (e.g. 3 for 2/3). -geometry WxH Same as -scale WxH -scale_cursor frac By default if -scale is supplied the cursor shape is scaled by the same factor. Depending on your usage, you may want to scale the cursor independently of the screen or not at all. If you specify -scale_cursor the cursor will be scaled by that factor. When using -scale mode to keep the cursor at its "natural" size use "-scale_cursor 1". Most of the ":" scaling options apply here as well. -viewonly All VNC clients can only watch (default off). -shared VNC display is shared, i.e. more than one viewer can connect at the same time (default off). -once Exit after the first successfully connected viewer disconnects, opposite of -forever. This is the Default. -forever Keep listening for more connections rather than exiting as soon as the first client(s) disconnect. Same as -many To get the standard non-shared VNC behavior where when a new VNC client connects the existing VNC client is dropped use: -nevershared -forever This method can also be used to guard against hung TCP connections that do not go away. -loop Create an outer loop restarting the x11vnc process whenever it terminates. -bg and -inetd are ignored in this mode (however see -loopbg below). Useful for continuing even if the X server terminates and restarts (at that moment the process will need permission to reconnect to the new X server of course). Use, e.g., -loop100 to sleep 100 millisecs between restarts, etc. Default is 2000ms (i.e. 2 secs) Use, e.g. -loop300,5 to sleep 300 ms and only loop 5 times. If -loopbg (plus any numbers) is specified instead, the "-bg" option is implied and the mode approximates inetd(8) usage to some degree. In this case when it goes into the background any listening sockets (i.e. ports 5900, 5800) are closed, so the next one in the loop can use them. This mode will only be of use if a VNC client (the only client for that process) is already connected before the process goes into the background, for example, usage of -display WAIT:.., -svc, and -connect can make use of this "poor man's" inetd mode. The default wait time is 500ms in this mode. This usage could use useful: -svc -bg -loopbg -timeout n Exit unless a client connects within the first n seconds after startup. If there have been no connection attempts after n seconds x11vnc exits immediately. If a client is trying to connect but has not progressed to the normal operating state, x11vnc gives it a few more seconds to finish and exits if it does not make it to the normal state. For reverse connections via -connect or -connect_or_exit a timeout of n seconds will be set for all reverse connects. If the connect timeout alarm goes off, x11vnc will exit immediately. -sleepin n At startup sleep n seconds before proceeding (e.g. to allow redirs and listening clients to start up) If a range is given: '-sleepin min-max', a random value between min and max is slept. E.g. '-sleepin 0-20' and '-sleepin 10-30'. Floats are allowed too. -inetd Launched by inetd(8): stdio instead of listening socket. Note: if you are not redirecting stderr to a log file (via shell 2> or -o option) you MUST also specify the -q option, otherwise the stderr goes to the viewer which will cause it to abort. Specifying both -inetd and -q and no -o will automatically close the stderr. -tightfilexfer Enable the TightVNC file transfer extension. Note that that when the -viewonly option is supplied all file transfers are disabled. Also clients that log in viewonly cannot transfer files. However, if the remote control mechanism is used to change the global or per-client viewonly state the filetransfer permissions will NOT change. IMPORTANT: please understand if -tightfilexfer is specified and you run x11vnc as root for, say, inetd or display manager (gdm, kdm, ...) access and you do not have it switch users via the -users option, then VNC Viewers that connect are able to do filetransfer reads and writes as *root*. Also, tightfilexfer is disabled in -unixpw mode. -ultrafilexfer Note: to enable UltraVNC filetransfer and to get it to work you probably need to supply these LibVNCServer options: "-rfbversion 3.6 -permitfiletransfer" "-ultrafilexfer" is an alias for this combination. IMPORTANT: please understand if -ultrafilexfer is specified and you run x11vnc as root for, say, inetd or display manager (gdm, kdm, ...) access and you do not have it switch users via the -users option, then VNC Viewers that connect are able to do filetransfer reads and writes as *root*. Note that sadly you cannot do both -tightfilexfer and -ultrafilexfer at the same time because the latter requires setting the version to 3.6 and tightvnc will not do filetransfer when it sees that version number. -http Instead of using -httpdir (see below) to specify where the Java vncviewer applet is, have x11vnc try to *guess* where the directory is by looking relative to the program location and in standard locations (/usr/local/share/x11vnc/classes, etc). Under -ssl or -stunnel the ssl classes subdirectory is sought. -http_ssl As -http, but force lookup for ssl classes subdir. Note that for HTTPS, single-port Java applet delivery you can set X11VNC_HTTPS_DOWNLOAD_WAIT_TIME to the max number of seconds to wait for the applet download to finish. The default is 15. -avahi Use the Avahi/mDNS ZeroConf protocol to advertise this VNC server to the local network. (Related terms: Rendezvous, Bonjour). Depending on your setup, you may need to start avahi-daemon and open udp port 5353 in your firewall. You can set X11VNC_AVAHI_NAME, X11VNC_AVAHI_HOST, and/or X11VNC_AVAHI_PORT environment variables to override the default values. For example: -env X11VNC_AVAHI_NAME=wally If the avahi API cannot be found at build time, a helper program like avahi-publish(1) or dns-sd(1) will be tried -mdns Same as -avahi. -zeroconf Same as -avahi. -connect string For use with "vncviewer -listen" reverse connections. If "string" has the form "host" or "host:port" the connection is made once at startup. Use commas for a list of host's and host:port's. E.g. -connect host1,host2 or host1:0,host2:5678. Note that to reverse connect to multiple hosts at the same time you will likely need to also supply: -shared Note that unlike most vnc servers, x11vnc will require a password for reverse as well as for forward connections. (provided password auth has been enabled, -rfbauth, etc) If you do not want to require a password for reverse connections set X11VNC_REVERSE_CONNECTION_NO_AUTH=1 in your environment before starting x11vnc. If "string" contains "/" it is instead interpreted as a file to periodically check for new hosts. The first line is read and then the file is truncated. Be careful about the location of this file if x11vnc is running as root (e.g. via gdm(1), etc). Repeater mode: Some services provide an intermediate "vnc repeater": http://www.uvnc.com/addons/repeater.html (and also http://koti.mbnet.fi/jtko/ for linux port) that acts as a proxy/gateway. Modes like these require an initial string to be sent for the reverse connection before the VNC protocol is started. Here are the ways to do this: -connect pre=some_string+host:port -connect pre128=some_string+host:port -connect repeater=ID:1234+host:port -connect repeater=23.45.67.89::5501+host:port SSVNC notation is also supported: -connect repeater://host:port+ID:1234 As with normal -connect usage, if the repeater port is not supplied 5500 is assumed. The basic idea is between the special tag, e.g. "pre=" and "+" is the pre-string to be sent. Note that in this case host:port is the repeater server, NOT the vnc viewer. Somehow the pre-string tells the repeater server how to find the vnc viewer and connect you to it. In the case pre=some_string+host:port, "some_string" is simply sent. In the case preNNN=some_string+host:port "some_string" is sent in a null padded buffer of length NNN. repeater= is the same as pre250=, this is the ultravnc repeater buffer size. Strings like "\n" and "\r", etc. are expanded to newline and carriage return. "\c" is expanded to "," since the connect string is comma separated. See also the -proxy option below for additional ways to plumb reverse connections. Reverse SSL: using -connect in -ssl mode makes x11vnc act as an SSL client (initiates SSL connection) rather than an SSL server. The idea is x11vnc might be connecting to stunnel on the viewer side with the viewer in listening mode. If you do not want this behavior, use -env X11VNC_DISABLE_SSL_CLIENT_MODE=1. With this the viewer side can act as the SSL client as it normally does for forward connections. Reverse SSL Repeater mode: This will work, but note that if the VNC Client does any sort of a 'Fetch Cert' action before connecting, then the Repeater will likely drop the connection and both sides will need to restart. Consider the use of -connect_or_exit and -loop300,2 to have x11vnc reconnect once to the repeater after the fetch. You will probably also want to supply -sslonly to avoid x11vnc thinking the delay in response means the connection is VeNCrypt. The env var X11VNC_DISABLE_SSL_CLIENT_MODE=1 discussed above may also be useful (i.e. the viewer can do a forward connection as it normally does.) IPv6: as of x11vnc 0.9.10 the -connect option should connect to IPv6 hosts properly. If there are problems you can disable IPv6 by setting -DX11VNC_IPV6=0 in CPPFLAGS when configuring. If there problems connecting to IPv6 hosts consider a relay like the included inet6to4 script or the -proxy option. -connect_or_exit str As with -connect, except if none of the reverse connections succeed, then x11vnc shuts down immediately An easier to type alias for this option is '-coe' By the way, if you do not want x11vnc to listen on ANY interface use -rfbport 0 which is handy for the -connect_or_exit mode. -proxy string Use proxy in string (e.g. host:port) as a proxy for making reverse connections (-connect or -connect_or_exit options). Web proxies are supported, but note by default most of them only support destination connections to ports 443 or 563, so this might not be very useful (the viewer would need to listen on that port or the router would have to do a port redirection). A web proxy may be specified by either "host:port" or "http://host:port" (the port is required even if it is the common choices 80 or 8080) SOCKS4, SOCKS4a, and SOCKS5 are also supported. SOCKS proxies normally do not have restrictions on the destination port number. Use a format like this: socks://host:port or socks5://host:port. Note that ssh -D does not support SOCKS4a, so use socks5://. For socks:// SOCKS4 is used on a numerical IP and "localhost", otherwise SOCKS4a is used (and so the proxy tries to do the DNS lookup). An experimental mode is "-proxy http://host:port/..." Note the "/" after the port that distinguishes it from a normal web proxy. The port must be supplied even if it is the default 80. For this mode a GET is done to the supplied URL with the string host=H&port=P appended. H and P will be the -connect reverse connect host and port. Use the string "__END__" to disable the appending. The basic idea here is that maybe some cgi script provides the actual viewer hookup and tunnelling. How to actually achieve this within cgi, php, etc. is not clear... A custom web server or apache module would be straight-forward. Another experimental mode is "-proxy ssh://user@host" in which case a SSH tunnel is used for the proxying. "user@" is not needed unless your unix username is different on "host". For a non-standard SSH port use ssh://user@host:port. If proxies are chained (see next paragraph) then the ssh one must be the first one. If ssh-agent is not active, then the ssh password needs to be entered in the terminal where x11vnc is running. Examples: -connect localhost:0 -proxy ssh://me@friends-pc:2222 -connect snoopy:0 -proxy ssh://ssh.company.com Multiple proxies may be chained together in case one needs to ricochet off of a number of hosts to finally reach the VNC viewer. Up to 3 may be chained, separate them by commas in the order they are to be connected to. E.g.: http://host1:port1,socks5://host2:port2 or three like: first,second,third IPv6: as of x11vnc 0.9.10 the -proxy option should connect to IPv6 hosts properly. If there are problems you can disable IPv6 by setting -DX11VNC_IPV6=0 in CPPFLAGS when configuring. If there problems connecting to IPv6 hosts consider a relay like the included inet6to4 script. -vncconnect Monitor the VNC_CONNECT X property set by the standard -novncconnect VNC program vncconnect(1). When the property is set to "host" or "host:port" establish a reverse connection. Using xprop(1) instead of vncconnect may work (see the FAQ). The -remote control mechanism uses X11VNC_REMOTE channel, and this option disables/enables it as well. Default: -vncconnect To use different names for these X11 properties (e.g. to have separate communication channels for multiple x11vnc's on the same display) set the VNC_CONNECT or X11VNC_REMOTE env. vars. to the string you want, for example: -env X11VNC_REMOTE=X11VNC_REMOTE_12345 Both sides of the channel must use the same unique name. The same can be done for the internal X11VNC_TICKER property (heartbeat and timestamp) if desired. -allow host1[,host2..] Only allow client connections from hosts matching the comma separated list of hostnames or IP addresses. Can also be a numerical IP prefix, e.g. "192.168.100." to match a simple subnet, for more control build LibVNCServer with libwrap support (See the FAQ). If the list contains a "/" it instead is a interpreted as a file containing addresses or prefixes that is re-read each time a new client connects. Lines can be commented out with the "#" character in the usual way. -allow applies in -ssl mode, but not in -stunnel mode. IPv6: as of x11vnc 0.9.10 a host can be specified in IPv6 numerical format, e.g. 2001:4860:b009::93. -localhost Basically the same as "-allow 127.0.0.1". Note: if you want to restrict which network interface x11vnc listens on, see the -listen option below. E.g. "-listen localhost" or "-listen 192.168.3.21". As a special case, the option "-localhost" implies "-listen localhost". A rare case, but for non-localhost -listen usage, if you use the remote control mechanism (-R) to change the -listen interface you may need to manually adjust the -allow list (and vice versa) to avoid situations where no connections (or too many) are allowed. If you do not want x11vnc to listen on ANY interface (evidently you are using -connect or -connect_or_exit, or plan to use remote control: -R connect:host), use -rfbport 0 IPv6: if IPv6 is supported, this option automatically implies the IPv6 loopback address '::1' as well. -unixsock str Listen on the unix socket (AF_UNIX) 'str' for connections. This mode is for either local connections or a tunnel endpoint where one wants the file permission of the unix socket file to determine what can connect to it. (This currently requires an edit to libvnserver/rfbserver.c: comment out lines 310 and 311, 'close(sock)' and 'return NULL' in rfbserver.c after the setsockopt() call.) Note that to disable all tcp listening ports specify '-rfbport 0' and should be useful with this mode. Example: mkdir ~/s; chmod 700 ~/s; x11vnc -unixsock ~/s/mysock -rfbport 0 ... The SSVNC unix vncviewer can connect to unix sockets. -listen6 str When in IPv6 listen mode "-6", listen only on the network interface with address "str". It also works for link scope addresses (fe80::219:dbff:fee5:3f92%eth0) and IPv6 hostname strings (e.g. ipv6.google.com.) Use LibVNCServer -listen option for the IPv4 interface. -nolookup Do not use gethostbyname() or gethostbyaddr() to look up host names or IP numbers. Use this if name resolution is incorrectly set up and leads to long pauses as name lookups time out, etc. -input string Fine tuning of allowed user input. If "string" does not contain a comma "," the tuning applies only to normal clients. Otherwise the part before "," is for normal clients and the part after for view-only clients. "K" is for Keystroke input, "M" for Mouse-motion input, "B" for Button-click input, "C" is for Clipboard input, and "F" is for File transfer (ultravnc only). Their presence in the string enables that type of input. E.g. "-input M" means normal users can only move the mouse and "-input KMBCF,M" lets normal users do anything and enables view-only users to move the mouse. This option is ignored when a global -viewonly is in effect (all input is discarded in that case). -grabkbd When VNC viewers are connected, attempt to the grab the keyboard so a (non-malicious) user sitting at the physical display is not able to enter keystrokes. This method uses XGrabKeyboard(3X11) and so it is not secure and does not rule out the person at the physical display injecting keystrokes by flooding the server with them, grabbing the keyboard himself, etc. Some degree of cooperation from the person at the display is assumed. This is intended for remote help-desk or educational usage modes. Note: on some recent (12/2010) X servers and/or desktops, -grabkbd no longer works: it prevents the window manager from resizing windows and similar things. Try -ungrabboth below (might not work.) -grabptr As -grabkbd, but for the mouse pointer using XGrabPointer(3X11). Unfortunately due to the way the X server works, the mouse can still be moved around by the user at the physical display, but he will not be able to change window focus with it. Also some window managers that call XGrabServer(3X11) for resizes, etc, will act on the local user's input. Again, some degree of cooperation from the person at the display is assumed. -ungrabboth Whenever there is any input (either keyboard or pointer), ungrab *both* the keyboard and the pointer while injecting the synthetic input. This is to allow window managers, etc. a chance to grab. -grabalways Apply both -grabkbd and -grabptr even when no VNC viewers are connected. If you only want one of them, use the -R remote control to turn the other back on, e.g. -R nograbptr. -viewpasswd string Supply a 2nd password for view-only logins. The -passwd (full-access) password must also be supplied. -passwdfile filename Specify the LibVNCServer password via the first line of the file "filename" (instead of via -passwd on the command line where others might see it via ps(1)). See the descriptions below for how to supply multiple passwords, view-only passwords, to specify external programs for the authentication, and other features. If the filename is prefixed with "rm:" it will be removed after being read. Perhaps this is useful in limiting the readability of the file. In general, the password file should not be readable by untrusted users (BTW: neither should the VNC -rfbauth file: it is NOT encrypted, only obscured with a fixed key). If the filename is prefixed with "read:" it will periodically be checked for changes and reread. It is guaranteed to be reread just when a new client connects so that the latest passwords will be used. If "filename" is prefixed with "cmd:" then the string after the ":" is run as an external command: the output of the command will be interpreted as if it were read from a password file (see below). If the command does not exit with 0, then x11vnc terminates immediately. To specify more than 1000 passwords this way set X11VNC_MAX_PASSWDS before starting x11vnc. The environment variables are set as in -accept. Note that due to the VNC protocol only the first 8 characters of a password are used (DES key). If "filename" is prefixed with "custom:" then a custom password checker is supplied as an external command following the ":". The command will be run when a client authenticates. If the command exits with 0 the client is accepted, otherwise it is rejected. The environment variables are set as in -accept. The standard input to the custom command will be a decimal digit "len" followed by a newline. "len" specifies the challenge size and is usually 16 (the VNC spec). Then follows len bytes which is the random challenge string that was sent to the client. This is then followed by len more bytes holding the client's response (i.e. the challenge string encrypted via DES with the user password in the standard situation). The "custom:" scheme can be useful to implement dynamic passwords or to implement methods where longer passwords and/or different encryption algorithms are used. The latter will require customizing the VNC client as well. One could create an MD5SUM based scheme for example. File format for -passwdfile: If multiple non-blank lines exist in the file they are all taken as valid passwords. Blank lines are ignored. Password lines may be "commented out" (ignored) if they begin with the character "#" or the line contains the string "__SKIP__". Lines may be annotated by use of the "__COMM__" string: from it to the end of the line is ignored. An empty password may be specified via the "__EMPTY__" string on a line by itself (note your viewer might not accept empty passwords). If the string "__BEGIN_VIEWONLY__" appears on a line by itself, the remaining passwords are used for viewonly access. For compatibility, as a special case if the file contains only two password lines the 2nd one is automatically taken as the viewonly password. Otherwise the "__BEGIN_VIEWONLY__" token must be used to have viewonly passwords. (tip: make the 3rd and last line be "__BEGIN_VIEWONLY__" to have 2 full-access passwords) -showrfbauth filename Print to the screen the obscured VNC password kept in the rfbauth file "filename" and then exit. -unixpw [list] Use Unix username and password authentication. x11vnc will use the su(1) program to verify the user's password. [list] is an optional comma separated list of allowed Unix usernames. If the [list] string begins with the character "!" then the entire list is taken as an exclude list. See below for per-user options that can be applied. A familiar "login:" and "Password:" dialog is presented to the user on a black screen inside the vncviewer. The connection is dropped if the user fails to supply the correct password in 3 tries or does not send one before a 45 second timeout. Existing clients are view-only during this period. If the first character received is "Escape" then the unix username will not be displayed after "login:" as it is typed. This could be of use for VNC viewers that automatically type the username and password. Since the detailed behavior of su(1) can vary from OS to OS and for local configurations, test the mode before deployment to make sure it is working properly. x11vnc will attempt to be conservative and reject a login if anything abnormal occurs. One case to note: FreeBSD and the other BSD's by default it is impossible for the user running x11vnc to validate his *own* password via su(1) (commenting out the pam_self.so entry in /etc/pam.d/su eliminates this behavior). So the x11vnc login will always *FAIL* for this case (even when the correct password is supplied). A possible workaround for this on *BSD would be to start x11vnc as root with the "-users +nobody" option to immediately switch to user nobody where the su'ing will proceed normally. Another source of potential problems are PAM modules that prompt for extra info, e.g. password aging modules. These logins will fail as well even when the correct password is supplied. **IMPORTANT**: to prevent the Unix password being sent in *clear text* over the network, one of two schemes will be enforced: 1) the -ssl builtin SSL mode, or 2) require both -localhost and -stunnel be enabled. Method 1) ensures the traffic is encrypted between viewer and server. A PEM file will be required, see the discussion under -ssl below (under some circumstances a temporary one can be automatically generated). Method 2) requires the viewer connection to appear to come from the same machine x11vnc is running on (e.g. from a ssh -L port redirection). And that the -stunnel SSL mode be used for encryption over the network. (see the description of -stunnel below). Note: as a convenience, if you ssh(1) in and start x11vnc it will check if the environment variable SSH_CONNECTION is set and appears reasonable. If it does, then the -ssl or -stunnel requirement will be dropped since it is assumed you are using ssh for the encrypted tunnelling. -localhost is still enforced. Use -ssl or -stunnel to force SSL usage even if SSH_CONNECTION is set. To override the above restrictions you can set environment variables before starting x11vnc: Set UNIXPW_DISABLE_SSL=1 to disable requiring either -ssl or -stunnel (as under SSH_CONNECTION.) Evidently you will be using a different method to encrypt the data between the vncviewer and x11vnc: perhaps ssh(1) or an IPSEC VPN. -localhost is still enforced (however, see the next paragraph.) Set UNIXPW_DISABLE_LOCALHOST=1 to disable the -localhost requirement in -unixpw modes. One should never do this (i.e. allow the Unix passwords to be sniffed on the network.) This also disables the localhost requirement for reverse connections (see below.) Note that use of -localhost with ssh(1) (and no -unixpw) is roughly the same as requiring a Unix user login (since a Unix password or the user's public key authentication is used by sshd on the machine where x11vnc runs and only local connections from that machine are accepted). Regarding reverse connections (e.g. -R connect:host and -connect host), when the -localhost constraint is in effect then reverse connections can only be used to connect to the same machine x11vnc is running on (default port 5500). Please use a ssh or stunnel port redirection to the viewer machine to tunnel the reverse connection over an encrypted channel. In -inetd mode the Method 1) will be enforced (not Method 2). With -ssl in effect reverse connections are disabled. If you override this via env. var, be sure to also use encryption from the viewer to inetd. Tip: you can also have your own stunnel spawn x11vnc in -inetd mode (thereby bypassing inetd). See the FAQ for details. The user names in the comma separated [list] may have per-user options after a ":", e.g. "fred:opts" where "opts" is a "+" separated list of "viewonly", "fullaccess", "input=XXXX", or "deny", e.g. "karl,wally:viewonly,boss:input=M". For "input=" it is the K,M,B,C described under -input. If an item in the list is "*" that means those options apply to all users. It ALSO implies all users are allowed to log in after supplying a valid password. Use "deny" to explicitly deny some users if you use "*" to set a global option. If [list] begins with the "!" character then "*" is ignored for checking if the user is allowed, but the option values associated with it do apply as normal. There are also some utilities for checking passwords if [list] starts with the "%" character. See the quick_pw() function for more details. Description: "%-" or "%stdin" means read one line from stdin. "%env" means it is in $UNIXPW env var. A leading "%/" or "%." means read the first line from the filename that follows after the % character. % by itself means prompt for the username and password. Otherwise: %user:pass E.g. -unixpw %fred:swordfish For the other cases user:pass is read from the indicated source. If the password is correct 'Y user' is printed and the program exit code is 0. If the password is incorrect it prints 'N user' and the exit code is 1. If there is some other error the exit code is 2. This feature enables x11vnc to be a general unix user password checking tool; it could be used from scripts or other programs. These % password checks also apply to the -unixpw_nis and -unixpw_cmd options. For the % password check, if the env. var. UNIXPW_CMD is set to a command then it is run as the user (assuming the password is correct.) The output of the command is not printed, the program or script must manage that by some other means. The exit code of x11vnc will depend on the exit code of the command that is run. Use -nounixpw to disable unixpw mode if it was enabled earlier in the cmd line (e.g. -svc mode) -unixpw_nis [list] As -unixpw above, however do not use su(1) but rather use the traditional getpwnam(3) + crypt(3) method to verify passwords. All of the above -unixpw options and constraints apply. This mode requires that the encrypted passwords be readable. Encrypted passwords stored in /etc/shadow will be inaccessible unless x11vnc is run as root. This is called "NIS" mode simply because in most NIS setups user encrypted passwords are accessible (e.g. "ypcat passwd") by an ordinary user and so that user can authenticate ANY user. NIS is not required for this mode to work (only that getpwnam(3) return the encrypted password is required), but it is unlikely it will work (as an ordinary user) for most modern environments unless NIS is available. On the other hand, when x11vnc is run as root it will be able to to access /etc/shadow even if NIS is not available (note running as root is often done when running x11vnc from inetd and xdm/gdm/kdm). Looked at another way, if you do not want to use the su(1) method provided by -unixpw (i.e. su_verify()), you can run x11vnc as root and use -unixpw_nis. Any users with passwords in /etc/shadow can then be authenticated. In -unixpw_nis mode, under no circumstances is x11vnc's user password verifying function based on su called (i.e. the function su_verify() that runs /bin/su in a pseudoterminal to verify passwords.) However, if -unixpw_nis is used in conjunction with the -find and -create -display WAIT:... modes then, if x11vnc is running as root, /bin/su may be called externally to run the find or create commands. -unixpw_cmd cmd As -unixpw above, however do not use su(1) but rather run the externally supplied command "cmd". The first line of its stdin will be the username and the second line the received password. If the command exits with status 0 (success) the VNC user will be accepted. It will be rejected for any other return status. Dynamic passwords and non-unix passwords, e.g. LDAP, can be implemented this way by providing your own custom helper program. Note that the remote viewer is given 3 tries to enter the correct password, and so the program may be called in a row that many (or more) times. If a list of allowed users is needed to limit who can log in, use -unixpw [list] in addition to this option. In FINDDISPLAY and FINDCREATEDISPLAY modes the "cmd" will also be run with the RFB_UNIXPW_CMD_RUN env. var. non-empty and set to the corresponding display find/create command. The first two lines of input are the username and passwd as in the normal case described above. To support FINDDISPLAY and FINDCREATEDISPLAY, "cmd" should run the requested command as the user (and most likely refusing to run it if the password is not correct.) Here is an example script (note it has a hardwired bogus password "abc"!) #!/bin/sh # Example x11vnc -unixpw_cmd script. # Read the first two lines of stdin (user and passwd) read user read pass debug=0 if [ $debug = 1 ]; then echo "user: $user" 1>&2 echo "pass: $pass" 1>&2 env | egrep -i 'rfb|vnc' 1>&2 fi # Check if the password is valid. # (A real example would use ldap lookup, etc!) if [ "X$pass" != "Xabc" ]; then exit 1 # incorrect password fi if [ "X$RFB_UNIXPW_CMD_RUN" = "X" ]; then exit 0 # correct password else # Run the requested command (finddisplay) if [ $debug = 1 ]; then echo "run: $RFB_UNIXPW_CMD_RUN" 1>&2 fi exec /bin/su - "$user" -c "$RFB_UNIXPW_CMD_RUN" fi In -unixpw_cmd mode, under no circumstances is x11vnc's user password verifying function based on su called (i.e. the function su_verify() that runs /bin/su in a pseudoterminal to verify passwords.) It is up to the supplied unixpw_cmd to do user switching if desired and if it has the permissions to do so. -find Find the user's display using FINDDISPLAY. This is an alias for "-display WAIT:cmd=FINDDISPLAY". Note: if a -display occurs later on the command line it will override the -find setting. For this and the next few options see -display WAIT:... below for all of the details. -finddpy Run the FINDDISPLAY program, print out the found display (if any) and exit. Output is like: DISPLAY=:0.0 DISPLAY=:0.0,XPID=12345 or DISPLAY=:0.0,VT=7. XPID is the process ID of the found X server. VT is the Linux virtual terminal of the X server. -listdpy Have the FINDDISPLAY program list all of your displays (i.e. all the X displays on the local machine that you have access rights to). x11vnc then exits. -findauth [disp] Apply the -find/-finddpy heuristics to try to guess the XAUTHORITY file for DISPLAY 'disp'. If 'disp' is not supplied, then the value in the -display on the cmdline is used; failing that $DISPLAY is used; and failing that ":0" is used. x11vnc then exits. If nothing is printed out, that means no XAUTHORITY was found for 'disp'; i.e. failure. If "XAUTHORITY=" is printed out, that means use the default (i.e. do not set XAUTHORITY). If "XAUTHORITY=/path/to/file" is printed out, then use that file. XDM/GDM/KDM: if you are running x11vnc as root and want to find the XAUTHORITY before anyone has logged into an X session yet, use: x11vnc -env FD_XDM=1 -findauth ... (This will also find the XAUTHORITY if a user is already logged into the X session.) When running as root, FD_XDM=1 will be tried if the initial -findauth fails. -create First try to find the user's display using FINDDISPLAY, if that doesn't succeed create an X session via the FINDCREATEDISPLAY method. This is an alias for "-display WAIT:cmd=FINDCREATEDISPLAY-Xvfb". Note: if a -display occurs later on the command line it will override the -create setting. SSH NOTE: for both -find and -create you can (should!) add the "-localhost" option to force SSH tunnel access. -xdummy As in -create, except Xdummy instead of Xvfb. -xvnc As in -create, except Xvnc instead of Xvfb. -xvnc_redirect As in -create, except Xvnc.redirect instead of Xvfb. -xdummy_xvfb Sets WAIT:cmd=FINDCREATEDISPLAY-Xdummy,Xvfb -create_xsrv str Sets WAIT:cmd=FINDCREATEDISPLAY- Can be on cmdline after anything that sets WAIT:.. and other things (e.g. -svc, -xdmsvc) to adjust the X server list. Example: -svc ... -create_xsrv Xdummy,X -svc Terminal services mode based on SSL access. Alias for -display WAIT:cmd=FINDCREATEDISPLAY-Xvfb -unixpw -users unixpw= -ssl SAVE Also "-service". Note: if a -display, -unixpw, -users, or -ssl occurs later on the command line it will override the -svc setting. -svc_xdummy As -svc except Xdummy instead of Xvfb. -svc_xvnc As -svc except Xvnc instead of Xvfb. -svc_xdummy_xvfb As -svc with Xdummy,Xvfb. -xdmsvc Display manager Terminal services mode based on SSL. Alias for -display WAIT:cmd=FINDCREATEDISPLAY-Xvfb.xdmcp -unixpw -users unixpw= -ssl SAVE Also "-xdm_service". Note: if a -display, -unixpw, -users, or -ssl occurs later on the command line it will override the -xdmsvc setting. To create a session a user will have to first log in to the -unixpw dialog and then log in again to the XDM/GDM/KDM prompt. Subsequent re-connections will only require the -unixpw password. See the discussion under -display WAIT:... for more details about XDM, etc configuration. Remember to enable XDMCP in the xdm-config, gdm.conf, or kdmrc configuration file. See -display WAIT: for more info. -sshxdmsvc Display manager Terminal services mode based on SSH. Alias for -display WAIT:cmd=FINDCREATEDISPLAY-Xvfb.xdmcp -localhost. The -localhost option constrains connections to come in via a SSH tunnel (which will require a login). To create a session a user will also have to log into the XDM GDM KDM prompt. Subsequent re-connections will only only require the SSH login. See the discussion under -display WAIT:... for more details about XDM, etc configuration. Remember to enable XDMCP in the xdm-config, gdm.conf, or kdmrc configuration file. See -display WAIT: for more info. -unixpw_system_greeter Present a "Press 'Escape' for System Greeter" option to the connecting VNC client in combined -unixpw and xdmcp FINDCREATEDISPLAY modes (e.g. -xdmsvc). Normally in a -unixpw mode the VNC client must supply a valid username and password to gain access. However, if -unixpw_system_greeter is supplied AND the FINDCREATEDISPLAY command matches 'xdmcp', then the user has the option to press Escape and then get a XDM/GDM/KDM login/greeter panel instead. They will then supply a username and password directly to the greeter. Otherwise, in xdmcp FINDCREATEDISPLAY mode the user must supply his username and password TWICE. First to the initial unixpw login dialog, and second to the subsequent XDM/GDM/KDM greeter. Note that if the user re-connects and supplies his username and password in the unixpw dialog the xdmcp greeter is skipped and he is connected directly to his existing X session. So the -unixpw_system_greeter option avoids the extra password at X session creation time. Example: x11vnc -xdmsvc -unixpw_system_greeter See -unixpw and -display WAIT:... for more info. The special options after a colon at the end of the username (e.g. user:solid) described under -display WAIT: are also applied in this mode if they are typed in before the user hits Escape. The username is ignored but the colon options are not. The default message is 2 lines in a small font, set the env. var. X11VNC_SYSTEM_GREETER1=true for a 1 line message in a larger font. If the user pressed Escape the FINDCREATEDISPLAY command will be run with the env. var. X11VNC_XDM_ONLY=1. Remember to enable XDMCP in the xdm-config, gdm.conf, or kdmrc configuration file. See -display WAIT: for more info. -redirect port As in FINDCREATEDISPLAY-Xvnc.redirect mode except redirect immediately (i.e. without X session finding or creation) to a VNC server listening on port. You can also supply host:port to redirect to a different machine. If 0 <= port < 200 it is taken as a VNC display (5900 is added to get the actual port), if port < 0 then -port is used. Probably the only reason to use the -redirect option is in conjunction with SSL support, e.g. -ssl SAVE. This provides an easy way to add SSL encryption to a VNC server that does not support SSL (e.g. Xvnc or vnc.so) In fact, the protocol does not even need to be VNC, and so "-rfbport port1 -ssl SAVE -redirect host:port2" can act as a replacement for stunnel(1). This mode only allows one redirected connection. The -forever option does not apply. Use -inetd or -loop for persistent service. -display WAIT:... A special usage mode for the normal -display option. Useful with -unixpw, but can be used independently of it. If the display string begins with WAIT: then x11vnc waits until a VNC client connects before opening the X display (or -rawfb device). This could be useful for delaying opening the display for certain usage modes (say if x11vnc is started at boot time and no X server is running or users logged in yet). If the string is, e.g. WAIT:0.0 or WAIT:1, i.e. "WAIT" in front of a normal X display, then that indicated display is used. One can also insert a geometry between colons, e.g. WAIT:1280x1024:... to set the size of the display the VNC client first attaches to since some VNC viewers will not automatically adjust to a new framebuffer size. A more interesting case is like this: WAIT:cmd=/usr/local/bin/find_display in which case the command after "cmd=" is run to dynamically work out the DISPLAY and optionally the XAUTHORITY data. The first line of the command output must be of the form DISPLAY=. 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= or raw xauthority data for the display. For example; xauth extract - $DISPLAY" NOTE: As specified in the previous paragraph, you can supply your own WAIT:cmd=... program or script, BUT there are two very useful *BUILT-IN* ones: FINDDISPLAY (alias -find above) and FINDCREATEDISPLAY (alias -create above.) Most people use these instead of creating their own script. Read the following (especially the BUILT-IN modes sections) to see how to configure these two useful builtin -display WAIT: modes. In the case of -unixpw (and -unixpw_nis only if x11vnc is running as root), then the cmd= command is run as the user who just authenticated via the login and password prompt. In the case of -unixpw_cmd, the commands will also be run as the logged-in user, as long as the user-supplied helper program supports RFB_UNIXPW_CMD_RUN (see the -unixpw_cmd option.) Also in the case of -unixpw, the user logging in can place a colon at the end of her username and supply a few options: scale=, scale_cursor= (or sc=), solid (or so), id=, clear_mods (or cm), clear_keys (or ck), clear_all (or ca), repeat, speeds= (or sp=), readtimeout= (or rd=), viewonly (or vo), nodisplay= (or nd=), rotate= (or ro=), or noncache (or nc), all separated by commas if there is more than one. After the user logs in successfully, these options will be applied to the VNC screen. For example, login: fred:scale=3/4,sc=1,repeat Password: ... login: runge:sp=modem,rd=120,solid for convenience m/n implies scale= e.g. fred:3/4 If you type and enter your password incorrectly, to retrieve your long "login:" line press the Up arrow once (before typing anything else). Most of these colon options only apply to the builtin FINDDISPLAY and FINDCREATEDISPLAY modes, but note that they are passed to the extrenal command in the environment as well and so could be used. In the login panel, press F1 to get a list of the available options that you can add after the username. Another option is "geom=WxH" or "geom=WxHxD" (or ge=). This only has an effect in FINDCREATEDISPLAY mode when a virtual X server such as Xvfb is going to be created. It sets the width and height of the new display, and optionally the color depth as well. You can also supply "gnome", "kde", "twm", "fvwm", "mwm", "dtwm", "wmaker", "xfce", "lxde", "enlightenment", "Xsession", or "failsafe" (same as "xterm") to have the created display use that mode for the user session. Specify "tag=..." to set the unique FD_TAG desktop session tag described below. Note: this option will be ignored if the FD_TAG env. var. is already set or if the viewer-side supplied value is not completely composed of alphanumeric or '_' or '-' characters. User preferences file: Instead of having the user type in geom=WxH,... etc. every time he logs in to find or create his X session, if you set FD_USERPREFS to a string that does not contain the "/" character, then the user's home directory is prepended to that string and if the file exists its first line is read and appended to any options he supplied at the login: prompt. For example -env FD_USERPREFS=.x11vnc_create and the user put "geom=1600x1200" in his ~/.x11vnc_create file. To disable the option setting set the environment variable X11VNC_NO_UNIXPW_OPTS=1 before starting x11vnc. To set any other options, the user can use the gui (x11vnc -gui connect) or the remote control method (x11vnc -R opt:val) during his VNC session. So we see the combination of -display WAIT:cmd=... and -unixpw allows automatic pairing of an unix authenticated VNC user with his desktop. This could be very useful on SunRays and also any system where multiple users share a given machine. The user does not need to remember special ports or passwords set up for his desktop and VNC. A nice way to use WAIT:cmd=... is out of inetd(8) (it automatically forks a new x11vnc for each user). You can have the x11vnc inetd spawned process run as, say, root or nobody. When run as root (for either inetd or display manager), you can also supply the option "-users unixpw=" to have the x11vnc process switch to the user as well. Note: there will be a 2nd SSL helper process that will not switch, but it is only encoding and decoding the encrypted stream at that point. BUILT-IN modes: -- Automatic Finding of User X Sessions -- As a special case, WAIT:cmd=FINDDISPLAY will run a script that works on most Unixes to determine a user's DISPLAY variable and xauthority data (see who(1)). NOTE: The option "-find" is an alias for this mode. To have this default script printed to stdout (e.g. for customization) run with WAIT:cmd=FINDDISPLAY-print To have the script run to print what display it would find use "-finddpy" or WAIT:cmd=FINDDISPLAY-run The standard script runs xdpyinfo(1) run on potential displays. If your X server(s) have a login greeter that exclusively grabs the Xserver, then xdpyinfo blocks forever and this mode will not work. See www.karlrunge.com/x11vnc/faq.html#faq-display-manager for how to disable this for dtgreet on Solaris and possibly for other greeters. In -find/cmd=FINDDISPLAY mode, if you set FD_XDM=1, e.g. 'x11vnc -env FD_XDM=1 -find ...' and x11vnc is running as root (e.g. inetd) then it will try to find the XAUTHORITY file of a running XDM/GDM/KDM login greeter (i.e. no user has logged into an X session yet.) As another special case, WAIT:cmd=HTTPONCE will allow x11vnc to service one http request and then exit. This is usually done in -inetd mode to run on, say, port 5800 and allow the Java vncviewer to be downloaded by client web browsers. For example: 5815 stream tcp nowait root /usr/sbin/tcpd /.../x11vnc \ -inetd -q -http_ssl -prog /.../x11vnc \ -display WAIT:cmd=HTTPONCE Where /.../x11vnc is the full path to x11vnc. It is used in the Apache SSL-portal example (see FAQ). In this mode you can set X11VNC_SKIP_DISPLAY to a comma separated list of displays (e.g. ":0,:1") to ignore in the finding process. The ":" is optional. Ranges n-m e.g. 0-20 can also be supplied. This string can also be set by the connecting user via "nd=" using "+" instead of "," If "nd=all" or you set X11VNC_SKIP_DISPLAY=all then all display finding fails as if you set X11VNC_FINDDISPLAY_ALWAYS_FAILS=1 (below.) On some systems lsof(1) can be very slow. Set the env. var. FIND_DISPLAY_NO_LSOF=1 to skip using lsof to try to find the Linux VT the X server is running on. set FIND_DISPLAY_NO_VT_FIND=1 to avoid looking at all. -- Automatic Creation of User X Sessions -- An interesting option is WAIT:cmd=FINDCREATEDISPLAY that is like FINDDISPLAY in that is uses the same method to find an existing display. However, if it does not find one it will try to *start* up an X server session for the user. This is the only time x11vnc tries to actually start up an X server. NOTE: The option "-create" is an alias for this mode. It will start looking for an open display number at :20 Override via X11VNC_CREATE_STARTING_DISPLAY_NUMBER=n By default 80 X displays are allowed (i.e. going to :99) Override via X11VNC_CREATE_MAX_DISPLAYS=n For its heuristics, the create display script sets LC_ALL=C so that command output is uniform. By default it will try to restore LC_ALL right before starting the user session. However, if you don't mind it keeping LC_ALL=C set the env. var.: X11VNC_CREATE_LC_ALL_C_OK=1 By default FINDCREATEDISPLAY will try Xvfb and then Xdummy: The Xdummy wrapper is part of the x11vnc source code (x11vnc/misc/Xdummy) It should be available in PATH and have run "Xdummy -install" once to create the shared library. Xdummy only works on Linux. As of 12/2009 it no longer needs to be run as root, and the default is to not run as root. In some circumstances permissions may require running it as root, in these cases specify FD_XDUMMY_RUN_AS_ROOT=1, this is the same as supplying -root to the Xdummy cmdline. Xvfb is available on most platforms and does not require root. An advantage of Xdummy over Xvfb is that Xdummy supports RANDR dynamic screen resizing. When x11vnc exits (i.e. user disconnects) the X server session stays running in the background. The FINDDISPLAY will find it directly next time. The user must exit the X session in the usual way for it to terminate (or kill the X server process if all else fails). To troubleshoot the FINDCREATEDISPLAY mechanism, set the following env. var. to an output log file, e.g -env CREATE_DISPLAY_OUTPUT=/tmp/mydebug.txt So this is a somewhat odd mode for x11vnc in that it will start up and poll virtual X servers! This can be used from, say, inetd(8) to provide a means of definitely getting a desktop (either real or virtual) on the machine. E.g. a desktop service: 5900 stream tcp nowait root /usr/sbin/tcpd /.../x11vnc -inetd -q -http -ssl SAVE -unixpw -users unixpw=\ -passwd secret -prog /.../x11vnc \ -display WAIT:cmd=FINDCREATEDISPLAY Where /.../x11vnc is the full path to x11vnc. See the -svc/-service option alias above. If for some reason you do not want x11vnc to ever try to find an existing display set the env. var X11VNC_FINDDISPLAY_ALWAYS_FAILS=1 (also -env ...) This is the same as setting X11VNC_SKIP_DISPLAY=all or supplying "nd=all" after "username:" Use WAIT:cmd=FINDCREATEDISPLAY-print to print out the script that is used for this. You can specify the preferred X server order via e.g., WAIT:cmd=FINDCREATEDISPLAY-Xdummy,Xvfb,X and/or leave out ones you do not want. The the case "X" means try to start up a real, hardware X server using xinit(1) or startx(1). If there is already an X server running the X case may only work on Linux (see startx(1)). "Xvnc" will start up a VNC X server (real- or tight-vnc, e.g. use if Xvfb is not available). "Xsrv" will start up the server program in the variable "FD_XSRV" if it is non-empty. You can make this be a wrapper script if you like (it must handle :N, -geometry, and -depth and other X server options). You can set the environment variable FD_GEOM (or X11VNC_CREATE_GEOM) to WxH or WxHxD to set the width and height and optionally the color depth of the created display. You can also set FD_SESS to be the session (short name of the windowmanager: kde, gnome, twm, failsafe, etc.). FD_OPTS contains extra options to pass to the X server. You can also set FD_PROG to be the full path to the session/windowmanager program. More FD tricks: FD_CUPS=port or FD_CUPS=host:port will set the cups printing environment. Similarly for FD_ESD=port or FD_ESD=host:port for esddsp sound redirection. Set FD_EXTRA to a command to be run a few seconds after the X server starts up. Set FD_TAG to be a unique name for the session, it is set as an X property, that makes FINDDISPLAY only find sessions with that tag value. Set FD_XDMCP_IF to the network interface that the display manager is running on; default is 'localhost' but you may need to set it to '::1' on some IPv6 only systems or misconfigured display managers. If you want the FINDCREATEDISPLAY session to contact an XDMCP login manager (xdm/gdm/kdm) on the same machine, then use "Xvfb.xdmcp" instead of "Xvfb", etc. The user will have to supply his username and password one more time (but he gets to select his desktop type so that can be useful). For this to work, you will need to enable localhost XDMCP (udp port 177) for the display manager. This seems to be: for gdm in gdm.conf: Enable=true in section [xdmcp] for kdm in kdmrc: Enable=true in section [Xdmcp] for xdm in xdm-config: DisplayManager.requestPort: 177 See the shorthand options above "-svc", "-xdmsvc" and "-sshxdmsvc" that specify the above options for some useful cases. If you set the env. var WAITBG=1 x11vnc will go into the background once listening in wait mode. Another special mode is FINDCREATEDISPLAY-Xvnc.redirect, (or FINDDISPLAY-Xvnc.redirect). In this case it will start up Xvnc as above if needed, but instead of polling it in its normal way, it simply does a socket redirection of the connected VNC viewer to the Xvnc. So in Xvnc.redirect x11vnc does no VNC but merely transfers the data back and forth. This should be faster then x11vnc's polling method, but not as fast as connecting directly to the Xvnc with the VNC Viewer. The idea here is to take advantage of x11vnc's display finding/creating scheme, SSL, and perhaps a few others. Most of x11vnc's options do not apply in this mode. Xvnc.redirect should also work for the vnc.so X server module for the h/w display however it will work only for finding the display and the user must already be logged into the X console. -vencrypt mode The VeNCrypt extension to the VNC protocol allows encrypted SSL/TLS connections. If the -ssl mode is enabled, then VeNCrypt is enabled as well BY DEFAULT (they both use a SSL/TLS tunnel, only the protocol handshake is a little different.) To control when and how VeNCrypt is used, specify the mode string. If mode is "never", then VeNCrypt is not used. If mode is "support" (the default) then VeNCrypt is supported. If mode is "only", then the similar and older ANONTLS protocol is not simultaneously supported. x11vnc's normal SSL mode (vncs://) will be supported under -ssl unless you set mode to "force". If mode is prefixed with "nodh:", then Diffie Hellman anonymous key exchange is disabled. If mode is prefixed with "nox509:", then X509 key exchange is disabled. To disable all Anonymous Diffie-Hellman access (susceptible to Man-In-The-Middle attack) you will need to supply "-vencrypt nodh:support -anontls never" or "-vencrypt nodh:only" If mode is prefixed with "newdh:", then new Diffie Hellman parameters are generated for each connection (this can be time consuming: 1-60 secs; see -dhparams below for a faster way) rather than using the fixed values in the program. Using fixed, publicly known values is not known to be a security problem. This setting applies to ANONTLS as well. Long example: -vencrypt newdh:nox509:support Also, if mode is prefixed with "plain:", then if -unixpw mode is active the VeNCrypt "*Plain" username+passwd method is enabled for Unix logins. Otherwise in -unixpw mode the normal login panel is provided. You *MUST* supply the -ssl option for VeNCrypt to be active. The -vencrypt option only fine-tunes its operation. -anontls mode The ANONTLS extension to the VNC protocol allows encrypted SSL/TLS connections. If the -ssl mode is enabled, then ANONTLS is enabled as well BY DEFAULT (they both use a SSL/TLS tunnel, only the protocol handshake is a little different.) ANONTLS is an older SSL/TLS mode introduced by vino. It is referred to as 'TLS' for its registered VNC security-type name, but we use the more descriptive 'ANONTLS' here because it provides only Anonymous Diffie-Hellman encrypted connections, and hence no possibility for certificate authentication. To control when and how ANONTLS is used, specify the mode string. If mode is "never", then ANONTLS is not used. If mode is "support" (the default) then ANONTLS is supported. If mode is "only", then the similar VeNCrypt protocol is not simultaneously supported. x11vnc's normal SSL mode (vncs://) will be supported under -ssl unless you set mode to "force". If mode is prefixed with "newdh:", then new Diffie Hellman parameters are generated for each connection (this can be time consuming: 1-60 secs; see -dhparams below for a faster way) rather than using the fixed values in the program. Using fixed, publicly known values is not known to be a security problem. This setting applies to VeNCrypt as well. See the description of "plain:" under -vencrypt. Long example: -anontls newdh:plain:support You *MUST* supply the -ssl option for ANONTLS to be active. The -anontls option only fine-tunes its operation. -sslonly Same as: "-vencrypt never -anontls never" i.e. it disables the VeNCrypt and ANONTLS encryption methods and only allows standard SSL tunneling. You must also supply the -ssl ... option (see below.) -dhparams file For some operations a set of Diffie Hellman parameters (prime and generator) is needed. If so, use the parameters in "file". In particular, the VeNCrypt and ANONTLS anonymous DH mode need them. By default a fixed set is used. If you do not want to do that you can specify "newdh:" to the -vencrypt and -anontls options to generate a new set each session. If that is too slow for you, use -dhparams file to a set you created manually via "openssl dhparam -out file 1024" -nossl Disable the -ssl option (see below). Since -ssl is off by default -nossl would only be used on the commandline to unset any *earlier* -ssl option (or -svc...) -ssl [pem] Use the openssl library (www.openssl.org) to provide a built-in encrypted SSL/TLS tunnel between VNC viewers and x11vnc. This requires libssl support to be compiled into x11vnc at build time. If x11vnc is not built with libssl support it will exit immediately when -ssl is prescribed. See the -stunnel option below for an alternative. The VNC Viewer-side needs to support SSL/TLS as well. See this URL and also the discussion below for ideas on how to enable SSL support for the viewer: http://www.karlrunge.com/x11vnc/faq.html#faq-ssl-tun nel-viewers . x11vnc provides an SSL enabled Java viewer applet in the classes/ssl directory (-http or -httpdir options.) The SSVNC viewer package supports SSL tunnels too. If the VNC Viewer supports VeNCrypt or ANONTLS (vino's encryption mode) they are also supported by the -ssl mode (see the -vencrypt and -anontls options for more info; use -sslonly to disable both of them.) Use "-ssl /path/to/mycert.pem" to specify an SSL certificate file in PEM format to use to identify and provide a key for this server. See openssl(1) for more info about PEMs and the -sslGenCert and "-ssl SAVE" options below for how to create them. The connecting VNC viewer SSL tunnel can (at its option) authenticate this server if it has the public key part of the certificate (or a common certificate authority, CA, is a more sophisticated way to verify this server's cert, see -sslGenCA below). This authentication is done to prevent Man-In-The-Middle attacks. Otherwise, if the VNC viewer simply accepts this server's key WITHOUT verification, the traffic is protected from passive sniffing on the network, but *NOT* from Man-In-The-Middle attacks. There are hacker tools like dsniff/webmitm and cain that implement SSL Man-In-The-Middle attacks. If [pem] is empty or the string "SAVE" then the openssl(1) command must be available to generate the certificate the first time. A self-signed certificate is generated (see -sslGenCA and -sslGenCert for use of a Certificate Authority.) It will be saved to the file ~/.vnc/certs/server.pem. On subsequent calls if that file already exists it will be used directly. Use "SAVE_NOPROMPT" to avoid being prompted to protect the generated key with a passphrase. However in -inetd and -bg modes there will be no prompting for a passphrase in either case. If [pem] is "SAVE_PROMPT" the server.pem certificate will be created based on your answers to its prompts for all info such as OrganizationalName, CommonName, etc. Use "SAVE-" and "SAVE_PROMPT-" to refer to the file ~/.vnc/certs/server-.pem instead (it will be generated if it does not already exist). E.g. "SAVE-charlie" will store to the file ~/.vnc/certs/server-charlie.pem Examples: x11vnc -ssl SAVE -display :0 ... x11vnc -ssl SAVE-someother -display :0 ... If [pem] is "TMP" and the openssl(1) utility command exists in PATH, then a temporary, self-signed certificate will be generated for this session. If openssl(1) cannot be used to generate a temporary certificate x11vnc exits immediately. The temporary cert will be discarded when x11vnc exits. If successful in using openssl(1) to generate a temporary certificate in "SAVE" or "TMP" creation modes, the public part of it will be displayed to stderr (e.g. one could copy it to the client-side to provide authentication of the server to VNC viewers.) NOTE: In "TMP" mode, unless you safely copy the public part of the temporary Cert to the viewer for authenticate *every time* (unlikely...), then only passive sniffing attacks are prevented and you are still open to Man-In-The-Middle attacks. This is why the default "SAVE" mode is preferred (and more sophisticated CA mode too). Only with saved keys AND the VNC viewer authenticating them (via the public certificate), are Man-In-The-Middle attacks prevented. If [pem] is "ANON" then the Diffie-Hellman anonymous key exchange method is used. In this mode there are *no* SSL certificates and so it is not possible to authenticate either the VNC server or VNC client. Thus only passive network sniffing attacks are avoided: the "ANON" method is susceptible to Man-In-The-Middle attacks. "ANON" is not recommended; instead use a SSL PEM you created or the default "SAVE" method. See -ssldir below to use a directory besides the default ~/.vnc/certs If your x11vnc binary was not compiled with OpenSSL library support, use of the -ssl option will induce an immediate failure and exit. For such binaries, consider using the -stunnel option for SSL encrypted connections. Misc Info: In temporary cert creation mode "TMP", set the env. var. X11VNC_SHOW_TMP_PEM=1 to have x11vnc print out the entire certificate, including the PRIVATE KEY part, to stderr. There are better ways to get/save this info. See "SAVE" above and "-sslGenCert" below. -ssltimeout n Set SSL read timeout to n seconds. In some situations (i.e. an iconified viewer in Windows) the viewer stops talking and the connection is dropped after the default timeout (25s for about the first minute, 43200s later). Set to zero to poll forever. Set to a negative value to use the builtin setting. Note that this value does NOT apply to the *initial* ssl init connection. The default timeout for that is 20sec. Use -env SSL_INIT_TIMEOUT=n to modify it. -sslnofail Exit at the first SSL connection failure. Useful when scripting SSL connections (e.g. x11vnc is started via ssh) and you do not want x11vnc waiting around for more connections, tying up ports, etc. -ssldir dir Use "dir" as an alternate ssl certificate and key management toplevel directory. The default is ~/.vnc/certs This directory is used to store server and other certificates and keys and also other materials. E.g. in the simplest case, "-ssl SAVE" will store the x11vnc server cert in dir/server.pem Use of alternate directories via -ssldir allows you to manage multiple VNC Certificate Authority (CA) keys. Another use is if ~/.vnc/cert is on an NFS share you might want your certificates and keys to be on a local filesystem to prevent network snooping (for example -ssldir /var/lib/x11vnc-certs). -ssldir affects nearly all of the other -ssl* options, e.g. -ssl SAVE, -sslGenCert, etc.. -sslverify path For either of the -ssl or -stunnel modes, use "path" to provide certificates to authenticate incoming VNC *Client* connections (normally only the server is authenticated in SSL.) This can be used as a method to replace standard password authentication of clients. If "path" is a directory it contains the client (or CA) certificates in separate files. If path is a file, it contains one or more certificates. See special tokens below. These correspond to the "CApath = dir" and "CAfile = file" stunnel options. See the stunnel(8) manpage for details. Examples: x11vnc -ssl -sslverify ~/my.crt x11vnc -ssl -sslverify ~/my_pem_dir/ Note that if path is a directory, it must contain the certs in separate files named like .0, where the value of is found by running the command "openssl x509 -hash -noout -in file.crt". Evidently one uses .1 if there is a collision... The the key-management utility "-sslCertInfo HASHON" and "-sslCertInfo HASHOFF" will create/delete these hashes for you automatically (via symlink) in the HASH subdirs it manages. Then you can point -sslverify to the HASH subdir. Special tokens: in -ssl mode, if "path" is not a file or a directory, it is taken as a comma separated list of tokens that are interpreted as follows: If a token is "CA" that means load the CA/cacert.pem file from the ssl directory. If a token is "clients" then all the files clients/*.crt in the ssl directory are loaded. Otherwise the file clients/token.crt is attempted to be loaded. As a kludge, use a token like ../server-foo to load a server cert if you find that necessary. Use -ssldir to use a directory different from the ~/.vnc/certs default. Note that if the "CA" cert is loaded you do not need to load any of the certs that have been signed by it. You will need to load any additional self-signed certs however. Examples: x11vnc -ssl -sslverify CA x11vnc -ssl -sslverify self:fred,self:jim x11vnc -ssl -sslverify CA,clients Usually "-sslverify CA" is the most effective. See the -sslGenCA and -sslGenCert options below for how to set up and manage the CA framework. NOTE: the following utilities, -sslGenCA, -sslGenCert, -sslEncKey, -sslCertInfo, and -sslCRL are provided for completeness, but for casual usage they are overkill. They provide VNC Certificate Authority (CA) key creation and server / client key generation and signing. So they provide a basic Public Key management framework for VNC-ing with x11vnc. (note that they require openssl(1) be installed on the system) However, the simplest usage mode, "-ssl TMP" (where x11vnc automatically generates its own, self-signed, temporary key and the VNC viewers always accept it, e.g. accepting via a dialog box) is probably safe enough for most scenarios. CA management is not needed. To protect against Man-In-The-Middle attacks the "TMP" mode can be improved by using "-ssl SAVE" (same as "-ssl", i.e. the default) to have x11vnc create a longer term self-signed certificate, and then (safely) copy the corresponding public key cert to the desired client machines (care must be taken the private key part is not stolen; you will be prompted for a passphrase). So keep in mind no CA key creation or management (-sslGenCA and -sslGenCert) is needed for either of the above two common usage modes. One might want to use -sslGenCA and -sslGenCert if you had a large number of VNC client and server workstations. That way the administrator could generate a single CA key with -sslGenCA and distribute its certificate part to all of the workstations. Next, he could create signed VNC server keys (-sslGenCert server ...) for each workstation or user that then x11vnc would use to authenticate itself to any VNC client that has the CA cert. Optionally, the admin could also make it so the VNC clients themselves are authenticated to x11vnc (-sslGenCert client ...) For this -sslverify would be pointed to the CA cert (and/or self-signed certs). x11vnc will be able to use all of these cert and key files. On the VNC client side, they will need to be "imported" somehow. Web browsers have "Manage Certificates" actions as does the Java applet plugin Control Panel. stunnel can also use these files (see the ss_vncviewer example script in the FAQ and SSVNC.) -sslCRL path Set the Certificate Revocation Lists (CRL) to "path". This setting applies for both -ssl and -stunnel modes. If path is a file, the file contains one or more CRLs in PEM format. If path is a directory, it contains hash named files of CRLs in the usual OpenSSL manner. See the OpenSSL and stunnel(8) documentation for more info. This option only applies if -sslverify has been supplied: it checks for revocation along the certificate chain used to verify the VNC client. The -sslCRL setting will be ignored when -sslverify is not specified. Note that if a CRL's expiration date has passed, all SSL connections will fail regardless of if they are related to the subject of the CRL or not. Only rarely will one's x11vnc -ssl infrastructure be so large that this option would be useful (since normally maintaining the contents of the -sslverify file or directory should be enough.) However, when using x11vnc with a Certificate Authority (see -sslGenCA) to authenticate Clients via SSL/TLS, the -sslCRL option can be useful to revoke users' certs whose private SSL keys were lost or stolen (e.g. laptop.) This way a new CA cert+key does not need to be created and new signed client keys generated and distributed to all users. To create a CRL file with revoked certificates the commands 'openssl ca -revoke ...' and 'openssl ca -gencrl ...' are useful. (Run them in ~/.vnc/certs) -sslGenCA [dir] Generate your own Certificate Authority private key, certificate, and other files in directory [dir]. x11vnc then exits. If [dir] is not supplied, a -ssldir setting is used, or otherwise ~/.vnc/certs is used. This command also creates directories where server and client certs and keys will be stored. The openssl(1) program must be installed on the system and available in PATH. After the CA files and directories are created the x11vnc command exits; the VNC server is not run. You will be prompted for information to put into the CA certificate. The info does not have to be accurate just as long as clients accept the cert for VNC connections. You will also need to supply a passphrase of at least 4 characters for the CA private key. Once you have generated the CA you can distribute its certificate part, [dir]/CA/cacert.pem, to other workstations where VNC viewers will be run. One will need to "import" this certificate in the applications, e.g. Web browser, Java applet plugin, stunnel, etc. Next, you can create and sign keys using the CA with the -sslGenCert option below. Examples: x11vnc -sslGenCA x11vnc -sslGenCA ~/myCAdir x11vnc -ssldir ~/myCAdir -sslGenCA (the last two lines are equivalent) -sslGenCert type name Generate a VNC server or client certificate and private key pair signed by the CA created previously with -sslGenCA. The openssl(1) program must be installed on the system and available in PATH. After the Certificate is generated x11vnc exits; the VNC server is not run. The type of key to be generated is the string "type". It is either "server" (i.e. for use by x11vnc) or "client" (for a VNC viewer). Note that typically only "server" is used: the VNC clients authenticate themselves by a non-public-key method (e.g. VNC or unix password). "type" is required. An arbitrary default name you want to associate with the key is supplied by the "name" string. You can change it at the various prompts when creating the key. "name" is optional. If name is left blank for clients keys then "nobody" is used. If left blank for server keys, then the primary server key: "server.pem" is created (this is the saved one referenced by "-ssl SAVE" when the server is started) If "name" begins with the string "self:" then a self-signed certificate is created instead of one signed by your CA key. If "name" begins with the string "req:" then only a key (.key) and a certificate signing *request* (.req) are generated. You can then send the .req file to an external CA (even a professional one, e.g. Thawte) and then combine the .key and the received cert into the .pem file with the same basename. The distinction between "server" and "client" is simply the choice of output filenames and sub-directory. This makes it so the -ssl SAVE-name option can easily pick up the x11vnc PEM file this option generates. And similarly makes it easy for the -sslverify option to pick up your client certs. There is nothing special about the filename or directory location of either the "server" and "client" certs. You can rename the files or move them to wherever you like. Precede this option with -ssldir [dir] to use a directory other than the default ~/.vnc/certs You will need to run -sslGenCA on that directory first before doing any -sslGenCert key creation. Note you cannot recreate a cert with exactly the same distiguished name (DN) as an existing one. To do so, you will need to edit the [dir]/CA/index.txt file to delete the line. Similar to -sslGenCA, you will be prompted to fill in some information that will be recorded in the certificate when it is created. Tip: if you know the fully-qualified hostname other people will be connecting to, you can use that as the CommonName "CN" to avoid some applications (e.g. web browsers and java plugin) complaining that it does not match the hostname. You will also need to supply the CA private key passphrase to unlock the private key created from -sslGenCA. This private key is used to sign the server or client certificate. The "server" certs can be used by x11vnc directly by pointing to them via the -ssl [pem] option. The default file will be ~/.vnc/certs/server.pem. This one would be used by simply typing -ssl SAVE. The pem file contains both the certificate and the private key. server.crt file contains the cert only. The "client" cert + private key file will need to be copied and imported into the VNC viewer side applications (Web browser, Java plugin, stunnel, etc.) Once that is done you can delete the "client" private key file on this machine since it is only needed on the VNC viewer side. The, e.g. ~/.vnc/certs/clients/.pem contains both the cert and private key. The .crt contains the certificate only. NOTE: It is very important to know one should generate new keys with a passphrase. Otherwise if an untrusted user steals the key file he could use it to masquerade as the x11vnc server (or VNC viewer client). You will be prompted whether to encrypt the key with a passphrase or not. It is recommended that you do. One inconvenience to a passphrase is that it must be typed in EVERY time x11vnc or the client app is started up. Examples: x11vnc -sslGenCert server x11vnc -ssl SAVE -display :0 ... and then on viewer using ss_vncviewer stunnel wrapper (see the FAQ): ss_vncviewer -verify ./cacert.crt hostname:0 (this assumes the cacert.crt cert from -sslGenCA was safely copied to the VNC viewer machine where ss_vncviewer is run) Example using a name: x11vnc -sslGenCert server charlie x11vnc -ssl SAVE-charlie -display :0 ... Example for a client certificate (rarely used): [truncated]