diff options
Diffstat (limited to 'x11vnc/x11vnc.1')
| -rw-r--r-- | x11vnc/x11vnc.1 | 6962 |
1 files changed, 0 insertions, 6962 deletions
diff --git a/x11vnc/x11vnc.1 b/x11vnc/x11vnc.1 deleted file mode 100644 index d4dd0a2..0000000 --- a/x11vnc/x11vnc.1 +++ /dev/null @@ -1,6962 +0,0 @@ -.\" This file was automatically generated from x11vnc -help output. -.TH X11VNC "1" "December 2010" "x11vnc " "User Commands" -.SH NAME -x11vnc - allow VNC connections to real X11 displays - version: 0.9.13, lastmod: 2010-12-27 -.SH SYNOPSIS -.B x11vnc -[OPTION]... -.SH DESCRIPTION -.PP -Typical usage is: -.IP -Run this command in a shell on the remote machine "far-host" -with X session you wish to view: -.IP -x11vnc -display :0 -.IP -Then run this in another window on the machine you are sitting at: -.IP -vncviewer far-host:0 -.PP -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". -.PP -By default x11vnc will not allow the screen to be shared and it will exit -as soon as the client disconnects. See \fB-shared\fR and \fB-forever\fR below to override -these protections. See the FAQ for details how to tunnel the VNC connection -through an encrypted channel such as -.IR ssh (1). -In brief: -.IP -ssh \fB-t\fR \fB-L\fR 5900:localhost:5900 far-host 'x11vnc \fB-localhost\fR \fB-display\fR :0' -.PP -% vncviewer -encodings 'copyrect tight zrle hextile' localhost:0 -.PP -Also, use of a VNC password (-rfbauth or \fB-passwdfile)\fR is strongly recommended. -.PP -For additional info see: http://www.karlrunge.com/x11vnc/ -and http://www.karlrunge.com/x11vnc/faq.html -.PP -Config file support: if the file $HOME/.x11vncrc exists then each line in -it is treated as a single command line option. Disable with \fB-norc.\fR For -each option name, the leading character "-" is not required. E.g. a line -that is either "forever" or "\fB-forever\fR" may be used and are equivalent. -Likewise "wait 100" or "\fB-wait\fR \fI100\fR" 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). -.PP -.SH OPTIONS - -.PP -\fB-display\fR \fIdisp\fR -.IP -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 \fIdisp\fR. -.IP -See the description below of the "\fB-display\fR \fIWAIT:...\fR" -extensions, where alias "\fB-find\fR" will find the user's -display automatically, and "\fB-create\fR" will create a -Xvfb session if no session is found. -.PP -\fB-auth\fR \fIfile\fR -.IP -Set the X authority file to be \fIfile\fR, equivalent to -setting the XAUTHORITY environment variable to \fIfile\fR -before startup. Same as \fB-xauth\fR file. See -.IR Xsecurity (7) -, -.IR xauth (1) -man pages for more info. -.IP -Use '-auth guess' to have x11vnc use its \fB-findauth\fR -mechanism (described below) to try to guess the -XAUTHORITY filename and use it. -.IP -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 \fB-env\fR FD_XDM=1 \fB-auth\fR 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 \fB-auth\fR guess fails. -.PP -\fB-N\fR -.IP -If the X display is :N, try to set the VNC display to -also be :N This just sets the \fB-rfbport\fR option to 5900+N -The program will exit immediately if that port is not -available. The \fB-N\fR option only works with normal \fB-display\fR -usage, e.g. :0 or :8, \fB-N\fR is ignored in the \fB-display\fR -WAIT:..., \fB-create,\fR \fB-find,\fR \fB-svc,\fR \fB-redirect,\fR etc modes. -.PP -\fB-autoport\fR \fIn\fR -.IP -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. -.PP -\fB-rfbport\fR \fIstr\fR -.IP -The VNC port to listen on (a LibVNCServer option), e.g. -5900, 5901, etc. If specified as "\fB-rfbport\fR \fIPROMPT\fR" -then the x11vnc \fB-gui\fR is used to prompt the user to -enter the port number. -.PP -\fB-6\fR -.IP -IPv6 listening support. In addition to IPv4, the -IPv6 address is listened on for incoming connections. -The same port number as IPv4 is used. -.IP -NOTE: This x11vnc binary was compiled to have the -"-6" IPv6 listening mode ENABLED by default (CPPFLAGS -\fB-DX11VNC_LISTEN6=1).\fR So to disable IPv6 listening mode -you MUST supply the "\fB-no6\fR" option (see below.) -.IP -The "-6" mode works for both normal connections and -\fB-ssl\fR encrypted ones. Nearly everything is supported -for the IPv6 case, but there are a few exceptions. -See \fB-stunnel\fR for its IPv6 support. -.IP -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 \fB-nopiv4.\fR -.IP -If you have trouble compiling or running in IPv6 mode, -set \fB-DX11VNC_IPV6=0\fR in CPPFLAGS when configuring to -disable IPv6 support. -.PP -\fB-no6\fR -.IP -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".) -.PP -\fB-noipv6\fR -.IP -Do not try to use IPv6 for any listening or connecting -sockets. This includes both the listening service -port(s) and outgoing connections from \fB-connect,\fR -\fB-connect_or_exit,\fR or \fB-proxy.\fR Use this if you are having -problems due to IPv6. -.PP -\fB-noipv4\fR -.IP -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. -.PP -\fB-reopen\fR -.IP -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.) -.IP -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. -.PP -\fB-reflect\fR \fIhost:N\fR -.IP -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 \fB-shared\fR (use \fB-noshared\fR as a later -option to disable). See the discussion below under -\fB-rawfb\fR vnc:host:N for more details. -.PP -\fB-id\fR \fIwindowid\fR -.IP -Show the X window corresponding to \fIwindowid\fR 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 \fB-xrandr\fR mechanism is used to track resizes. Use -.IR xwininfo (1) -to get the window id, or use "\fB-id\fR \fIpick\fR" -to have x11vnc run -.IR xwininfo (1) -for you and extract -the id. The \fB-id\fR option is useful for exporting very -simple applications (e.g. the current view on a webcam). -.PP -\fB-sid\fR \fIwindowid\fR -.IP -As \fB-id,\fR 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. -.PP -\fB-appshare\fR -.IP -Simple application sharing based on the \fB-id/-sid\fR -mechanism. Every new toplevel window that the -application creates induces a new viewer window via -a reverse connection. The \fB-id/-sid\fR and \fB-connect\fR -options are required. Run 'x11vnc \fB-appshare\fR \fB-help'\fR -for more info. -.PP -\fB-clip\fR \fIWxH+X+Y\fR -.IP -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 \fB-id/-sid\fR -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. -.IP -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). -.PP -\fB-flashcmap\fR -.IP -In 8bpp indexed color, let the installed colormap flash -as the pointer moves from window to window (slow). -Also try the \fB-8to24\fR option to avoid flash altogether. -.PP -\fB-shiftcmap\fR \fIn\fR -.IP -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. \fIn\fR -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: \fB-shiftcmap\fR 240 -.PP -\fB-notruecolor\fR -.IP -For 8bpp displays, force indexed color (i.e. a colormap) -even if it looks like 8bpp TrueColor (rare problem). -.PP -\fB-advertise_truecolor\fR -.IP -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. -.PP -\fB-visual\fR \fIn\fR -.IP -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 -.IR 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 \fB-noshm\fR when using this option (so XGetImage may -automatically translate the pixel data). -.PP -\fB-overlay\fR -.IP -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). -.IP -Currently \fB-overlay\fR only works on Solaris via -.IR XReadScreen (3X11) -and IRIX using -.IR 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 "\fB-su\fR" argument to Xsun (in -/etc/dt/config/Xservers). -.IP -Use \fB-overlay\fR 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 \fB-overlay\fR is used. Another use of -\fB-overlay\fR is to enable showing the exact mouse cursor -shape (details below). -.IP -Under \fB-overlay,\fR performance will be somewhat slower -due to the extra image transformations required. -For optimal performance do not use \fB-overlay,\fR 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 \fB-use24\fR or \fB-visual\fR options). -.PP -\fB-overlay_nocursor\fR -.IP -Sets \fB-overlay,\fR but does not try to draw the exact mouse -cursor shape using the overlay mechanism. -.PP -\fB-8to24\fR \fI[opts]\fR -.IP -Try this option if \fB-overlay\fR 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. -.IP -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. -.IP -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. -.IP -Note that even if there are *no* depth 24 visuals or -windows (i.e. pure 8bpp), this mode is potentially -an improvement over \fB-flashcmap\fR because it avoids the -flashing and shows each window in the correct color. -.IP -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. -.IP -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 -\fB-fixscreen\fR 8=3.0 or \fB-fixscreen\fR V=3.0 may be used to -periodically refresh the screen at the cost of bandwidth -(every 3 sec for this example). -.IP -The [opts] string can contain the following settings. -Multiple settings are separated by commas. -.IP -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. -.IP -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) -.IP -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. -.IP -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. -.IP -While testing on a very old SS20 these options gave -tolerable response: \fB-8to24\fR poll=0.2,cachewin=5.0. For -this machine \fB-overlay\fR is supported and gives better -response. -.IP -Debugging for this mode can be enabled by setting -"dbg=1", "dbg=2", or "dbg=3". -.PP -\fB-24to32\fR -.IP -Very rare problem: if the framebuffer (X display -or \fB-rawfb)\fR 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. -.IP -In the case of \fB-rawfb\fR 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 -"\fB-noshm\fR \fI\fB-visual\fR TrueColor:32\fR". (If better performance -is needed for the latter, feel free to ask). -.PP -\fB-scale\fR \fIfraction\fR -.IP -Scale the framebuffer by factor \fIfraction\fR. Values -less than 1 shrink the fb, larger ones expand it. Note: -the image may not be sharp and response may be slower. -If \fIfraction\fR 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. \fB-scale\fR 2/3 -.IP -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' -.IP -Scaling Options: can be added after \fIfraction\fR via -":", to supply multiple ":" options use commas. -If you just want a quick, rough scaling without -blending, append ":nb" to \fIfraction\fR (e.g. \fB-scale\fR -1/3:nb). No blending is the default for 8bpp indexed -color, to force blending for this case use ":fb". -.IP -To disable \fB-scrollcopyrect\fR and \fB-wirecopyrect\fR under -\fB-scale\fR 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 -.IP -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). -.PP -\fB-geometry\fR \fIWxH\fR -.IP -Same as \fB-scale\fR WxH -.PP -\fB-scale_cursor\fR \fIfrac\fR -.IP -By default if \fB-scale\fR 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 \fB-scale_cursor\fR -the cursor will be scaled by that factor. When using -\fB-scale\fR mode to keep the cursor at its "natural" size -use "\fB-scale_cursor\fR \fI1\fR". Most of the ":" scaling -options apply here as well. -.PP -\fB-viewonly\fR -.IP -All VNC clients can only watch (default off). -.PP -\fB-shared\fR -.IP -VNC display is shared, i.e. more than one viewer can -connect at the same time (default off). -.PP -\fB-once\fR -.IP -Exit after the first successfully connected viewer -disconnects, opposite of \fB-forever.\fR This is the Default. -.PP -\fB-forever\fR -.IP -Keep listening for more connections rather than exiting -as soon as the first client(s) disconnect. Same as \fB-many\fR -.IP -To get the standard non-shared VNC behavior where when -a new VNC client connects the existing VNC client is -dropped use: \fB-nevershared\fR \fB-forever\fR This method can -also be used to guard against hung TCP connections that -do not go away. -.PP -\fB-loop\fR -.IP -Create an outer loop restarting the x11vnc process -whenever it terminates. \fB-bg\fR and \fB-inetd\fR are ignored -in this mode (however see \fB-loopbg\fR below). -.IP -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). -.IP -Use, e.g., \fB-loop100\fR to sleep 100 millisecs between -restarts, etc. Default is 2000ms (i.e. 2 secs) Use, -e.g. \fB-loop300,5\fR to sleep 300 ms and only loop 5 times. -.IP -If \fB-loopbg\fR (plus any numbers) is specified instead, -the "\fB-bg\fR" option is implied and the mode approximates -.IR 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 \fB-display\fR WAIT:.., -\fB-svc,\fR and \fB-connect\fR can make use of this "poor man's" -inetd mode. The default wait time is 500ms in this -mode. This usage could use useful: \fB-svc\fR \fB-bg\fR \fB-loopbg\fR -.PP -\fB-timeout\fR \fIn\fR -.IP -Exit unless a client connects within the first n seconds -after startup. -.IP -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. -.IP -For reverse connections via \fB-connect\fR or \fB-connect_or_exit\fR -a timeout of n seconds will be set for all reverse -connects. If the connect timeout alarm goes off, -x11vnc will exit immediately. -.PP -\fB-sleepin\fR \fIn\fR -.IP -At startup sleep n seconds before proceeding (e.g. to -allow redirs and listening clients to start up) -.IP -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. -.PP -\fB-inetd\fR -.IP -Launched by -.IR inetd (8): -stdio instead of listening socket. -Note: if you are not redirecting stderr to a log file -(via shell 2> or \fB-o\fR option) you MUST also specify the \fB-q\fR -option, otherwise the stderr goes to the viewer which -will cause it to abort. Specifying both \fB-inetd\fR and \fB-q\fR -and no \fB-o\fR will automatically close the stderr. -.PP -\fB-tightfilexfer\fR -.IP -Enable the TightVNC file transfer extension. Note that -that when the \fB-viewonly\fR 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. -.IP -IMPORTANT: please understand if \fB-tightfilexfer\fR 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 \fB-users\fR option, then -VNC Viewers that connect are able to do filetransfer -reads and writes as *root*. -.IP -Also, tightfilexfer is disabled in \fB-unixpw\fR mode. -.PP -\fB-ultrafilexfer\fR -.IP -Note: to enable UltraVNC filetransfer and to get it to -work you probably need to supply these LibVNCServer -options: "\fB-rfbversion\fR \fI3.6 \fB-permitfiletransfer\fR"\fR -"\fB-ultrafilexfer\fR" is an alias for this combination. -.IP -IMPORTANT: please understand if \fB-ultrafilexfer\fR 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 \fB-users\fR option, then -VNC Viewers that connect are able to do filetransfer -reads and writes as *root*. -.IP -Note that sadly you cannot do both \fB-tightfilexfer\fR and -\fB-ultrafilexfer\fR 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. -.PP -\fB-http\fR -.IP -Instead of using \fB-httpdir\fR (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 \fB-ssl\fR or -\fB-stunnel\fR the ssl classes subdirectory is sought. -.PP -\fB-http_ssl\fR -.IP -As \fB-http,\fR but force lookup for ssl classes subdir. -.IP -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. -.PP -\fB-avahi\fR -.IP -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. -.IP -You can set X11VNC_AVAHI_NAME, X11VNC_AVAHI_HOST, -and/or X11VNC_AVAHI_PORT environment variables -to override the default values. For example: -\fB-env\fR X11VNC_AVAHI_NAME=wally -.IP -If the avahi API cannot be found at build time, a helper -program like avahi- -.IR publish (1) -or dns- -.IR sd (1) -will be tried -.PP -\fB-mdns\fR -.IP -Same as \fB-avahi.\fR -.PP -\fB-zeroconf\fR -.IP -Same as \fB-avahi.\fR -.PP -\fB-connect\fR \fIstring\fR -.IP -For use with "vncviewer -listen" reverse connections. -If \fIstring\fR has the form "host" or "host:port" -the connection is made once at startup. -.IP -Use commas for a list of host's and host:port's. -E.g. \fB-connect\fR 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: \fB-shared\fR -.IP -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, \fB-rfbauth,\fR 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. -.IP -If \fIstring\fR 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 -.IR gdm (1) -, etc). -.IP -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: -.IP -\fB-connect\fR pre=some_string+host:port -\fB-connect\fR pre128=some_string+host:port -\fB-connect\fR repeater=ID:1234+host:port -\fB-connect\fR repeater=23.45.67.89::5501+host:port -.IP -SSVNC notation is also supported: -.IP -\fB-connect\fR repeater://host:port+ID:1234 -.IP -As with normal \fB-connect\fR usage, if the repeater port is -not supplied 5500 is assumed. -.IP -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. -.IP -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. -.IP -Strings like "\\n" and "\\r", etc. are expanded to -newline and carriage return. "\\c" is expanded to -"," since the connect string is comma separated. -.IP -See also the \fB-proxy\fR option below for additional ways -to plumb reverse connections. -.IP -Reverse SSL: using \fB-connect\fR in \fB-ssl\fR 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 \fB-env\fR X11VNC_DISABLE_SSL_CLIENT_MODE=1. -With this the viewer side can act as the SSL client -as it normally does for forward connections. -.IP -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 \fB-connect_or_exit\fR -and \fB-loop300,2\fR to have x11vnc reconnect once to the -repeater after the fetch. You will probably also want -to supply \fB-sslonly\fR 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.) -.IP -IPv6: as of x11vnc 0.9.10 the \fB-connect\fR option should -connect to IPv6 hosts properly. If there are problems -you can disable IPv6 by setting \fB-DX11VNC_IPV6=0\fR -in CPPFLAGS when configuring. If there problems -connecting to IPv6 hosts consider a relay like the -included inet6to4 script or the \fB-proxy\fR option. -.PP -\fB-connect_or_exit\fR \fIstr\fR -.IP -As with \fB-connect,\fR except if none of the reverse -connections succeed, then x11vnc shuts down immediately -.IP -An easier to type alias for this option is '-coe' -.IP -By the way, if you do not want x11vnc to listen on -ANY interface use \fB-rfbport\fR 0 which is handy for the -\fB-connect_or_exit\fR mode. -.PP -\fB-proxy\fR \fIstring\fR -.IP -Use proxy in string (e.g. host:port) as a proxy for -making reverse connections (-connect or \fB-connect_or_exit\fR -options). -.IP -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). -.IP -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) -.IP -SOCKS4, SOCKS4a, and SOCKS5 are also supported. -SOCKS proxies normally do not have restrictions on the -destination port number. -.IP -Use a format like this: socks://host:port or -socks5://host:port. Note that ssh \fB-D\fR 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). -.IP -An experimental mode is "\fB-proxy\fR \fIhttp://host:port/...\fR" -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 \fB-connect\fR 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. -.IP -Another experimental mode is "\fB-proxy\fR \fIssh://user@host\fR" -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: -.IP -\fB-connect\fR localhost:0 \fB-proxy\fR ssh://me@friends-pc:2222 -.IP -\fB-connect\fR snoopy:0 \fB-proxy\fR ssh://ssh.company.com -.IP -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 -.IP -IPv6: as of x11vnc 0.9.10 the \fB-proxy\fR option should -connect to IPv6 hosts properly. If there are problems -you can disable IPv6 by setting \fB-DX11VNC_IPV6=0\fR -in CPPFLAGS when configuring. If there problems -connecting to IPv6 hosts consider a relay like the -included inet6to4 script. -.PP -\fB-vncconnect,\fR \fB-novncconnect\fR -.IP -Monitor the VNC_CONNECT X property set by the standard -VNC program -.IR vncconnect (1). -When the property is -set to "host" or "host:port" establish a reverse -connection. Using -.IR xprop (1) -instead of vncconnect may -work (see the FAQ). The \fB-remote\fR control mechanism uses -X11VNC_REMOTE channel, and this option disables/enables -it as well. Default: \fB-vncconnect\fR -.IP -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: \fB-env\fR 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. -.PP -\fB-allow\fR \fIhost1[,host2..]\fR -.IP -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. -.IP -\fB-allow\fR applies in \fB-ssl\fR mode, but not in \fB-stunnel\fR mode. -.IP -IPv6: as of x11vnc 0.9.10 a host can be specified -in IPv6 numerical format, e.g. 2001:4860:b009::93. -.PP -\fB-localhost\fR -.IP -Basically the same as "\fB-allow\fR \fI127.0.0.1\fR". -.IP -Note: if you want to restrict which network interface -x11vnc listens on, see the \fB-listen\fR option below. -E.g. "\fB-listen\fR \fIlocalhost\fR" or "\fB-listen\fR \fI192.168.3.21\fR". -As a special case, the option "\fB-localhost\fR" implies -"\fB-listen\fR \fIlocalhost\fR". -.IP -A rare case, but for non-localhost \fB-listen\fR usage, if -you use the remote control mechanism (-R) to change -the \fB-listen\fR interface you may need to manually adjust -the \fB-allow\fR list (and vice versa) to avoid situations -where no connections (or too many) are allowed. -.IP -If you do not want x11vnc to listen on ANY interface -(evidently you are using \fB-connect\fR or \fB-connect_or_exit,\fR -or plan to use remote control: \fB-R\fR connect:host), use -\fB-rfbport\fR 0 -.IP -IPv6: if IPv6 is supported, this option automatically -implies the IPv6 loopback address '::1' as well. -.PP -\fB-unixsock\fR \fIstr\fR -.IP -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 \fB-unixsock\fR ~/s/mysock \fB-rfbport\fR 0 ... -The SSVNC unix vncviewer can connect to unix sockets. -.PP -\fB-listen6\fR \fIstr\fR -.IP -When in IPv6 listen mode "-6", listen only on the -network interface with address \fIstr\fR. It also works -for link scope addresses (fe80::219:dbff:fee5:3f92%eth0) -and IPv6 hostname strings (e.g. ipv6.google.com.) -Use LibVNCServer \fB-listen\fR option for the IPv4 interface. -.PP -\fB-nolookup\fR -.IP -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. -.PP -\fB-input\fR \fIstring\fR -.IP -Fine tuning of allowed user input. If \fIstring\fR 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. "\fB-input\fR \fIM\fR" means normal -users can only move the mouse and "\fB-input\fR \fIKMBCF,M\fR" -lets normal users do anything and enables view-only -users to move the mouse. This option is ignored when -a global \fB-viewonly\fR is in effect (all input is discarded -in that case). -.PP -\fB-grabkbd\fR -.IP -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 -.IR 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. -.IP -Note: on some recent (12/2010) X servers and/or -desktops, \fB-grabkbd\fR no longer works: it prevents the -window manager from resizing windows and similar things. -Try \fB-ungrabboth\fR below (might not work.) -.PP -\fB-grabptr\fR -.IP -As \fB-grabkbd,\fR but for the mouse pointer using -.IR 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 -.IR 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. -.PP -\fB-ungrabboth\fR -.IP -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. -.PP -\fB-grabalways\fR -.IP -Apply both \fB-grabkbd\fR and \fB-grabptr\fR even when no VNC -viewers are connected. If you only want one of them, -use the \fB-R\fR remote control to turn the other back on, -e.g. \fB-R\fR nograbptr. -.PP -\fB-viewpasswd\fR \fIstring\fR -.IP -Supply a 2nd password for view-only logins. The \fB-passwd\fR -(full-access) password must also be supplied. -.PP -\fB-passwdfile\fR \fIfilename\fR -.IP -Specify the LibVNCServer password via the first line -of the file \fIfilename\fR (instead of via \fB-passwd\fR on -the command line where others might see it via -.IR ps (1) -). -.IP -See the descriptions below for how to supply multiple -passwords, view-only passwords, to specify external -programs for the authentication, and other features. -.IP -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 \fB-rfbauth\fR file: it is NOT -encrypted, only obscured with a fixed key). -.IP -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. -.IP -If \fIfilename\fR 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 \fB-accept.\fR -.IP -Note that due to the VNC protocol only the first 8 -characters of a password are used (DES key). -.IP -If \fIfilename\fR 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 \fB-accept.\fR -.IP -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). -.IP -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. -.IP -File format for \fB-passwdfile:\fR -.IP -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). -.IP -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) -.PP -\fB-showrfbauth\fR \fIfilename\fR -.IP -Print to the screen the obscured VNC password kept in -the rfbauth file \fIfilename\fR and then exit. -.PP -\fB-unixpw\fR \fI[list]\fR -.IP -Use Unix username and password authentication. x11vnc -will use the -.IR 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. -.IP -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. -.IP -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. -.IP -Since the detailed behavior of -.IR 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. -.IP -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 -.IR 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). -.IP -A possible workaround for this on *BSD would be to -start x11vnc as root with the "\fB-users\fR \fI+nobody\fR" option -to immediately switch to user nobody where the su'ing -will proceed normally. -.IP -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. -.IP -**IMPORTANT**: to prevent the Unix password being sent -in *clear text* over the network, one of two schemes -will be enforced: 1) the \fB-ssl\fR builtin SSL mode, or 2) -require both \fB-localhost\fR and \fB-stunnel\fR be enabled. -.IP -Method 1) ensures the traffic is encrypted between -viewer and server. A PEM file will be required, see the -discussion under \fB-ssl\fR below (under some circumstances -a temporary one can be automatically generated). -.IP -Method 2) requires the viewer connection to appear -to come from the same machine x11vnc is running on -(e.g. from a ssh \fB-L\fR port redirection). And that the -\fB-stunnel\fR SSL mode be used for encryption over the -network. (see the description of \fB-stunnel\fR below). -.IP -Note: as a convenience, if you -.IR 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 \fB-ssl\fR or \fB-stunnel\fR requirement will be -dropped since it is assumed you are using ssh for the -encrypted tunnelling. \fB-localhost\fR is still enforced. -Use \fB-ssl\fR or \fB-stunnel\fR to force SSL usage even if -SSH_CONNECTION is set. -.IP -To override the above restrictions you can set -environment variables before starting x11vnc: -.IP -Set UNIXPW_DISABLE_SSL=1 to disable requiring either -\fB-ssl\fR or \fB-stunnel\fR (as under SSH_CONNECTION.) Evidently -you will be using a different method to encrypt the -data between the vncviewer and x11vnc: perhaps -.IR ssh (1) -or an IPSEC VPN. \fB-localhost\fR is still enforced (however, -see the next paragraph.) -.IP -Set UNIXPW_DISABLE_LOCALHOST=1 to disable the \fB-localhost\fR -requirement in \fB-unixpw\fR 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.) -.IP -Note that use of \fB-localhost\fR with -.IR ssh (1) -(and no \fB-unixpw)\fR -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). -.IP -Regarding reverse connections (e.g. \fB-R\fR connect:host -and \fB-connect\fR host), when the \fB-localhost\fR 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. -.IP -In \fB-inetd\fR mode the Method 1) will be enforced (not -Method 2). With \fB-ssl\fR 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 \fB-inetd\fR mode (thereby bypassing inetd). See the FAQ -for details. -.IP -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 \fB-input.\fR -.IP -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. -.IP -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. \fB-unixpw\fR %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 \fB-unixpw_nis\fR and \fB-unixpw_cmd\fR options. -.IP -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. -.IP -Use \fB-nounixpw\fR to disable unixpw mode if it was enabled -earlier in the cmd line (e.g. \fB-svc\fR mode) -.PP -\fB-unixpw_nis\fR \fI[list]\fR -.IP -As \fB-unixpw\fR above, however do not use -.IR su (1) -but rather -use the traditional -.IR getpwnam (3) -+ -.IR crypt (3) -method to -verify passwords. All of the above \fB-unixpw\fR options and -constraints apply. -.IP -This mode requires that the encrypted passwords be -readable. Encrypted passwords stored in /etc/shadow -will be inaccessible unless x11vnc is run as root. -.IP -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. -.IP -NIS is not required for this mode to work (only that -.IR 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). -.IP -Looked at another way, if you do not want to use the -.IR su (1) -method provided by \fB-unixpw\fR (i.e. su_verify()), you -can run x11vnc as root and use \fB-unixpw_nis.\fR Any users -with passwords in /etc/shadow can then be authenticated. -.IP -In \fB-unixpw_nis\fR 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 \fB-unixpw_nis\fR is used in conjunction with the \fB-find\fR -and \fB-create\fR \fB-display\fR WAIT:... modes then, if x11vnc is -running as root, /bin/su may be called externally to -run the find or create commands. -.PP -\fB-unixpw_cmd\fR \fIcmd\fR -.IP -As \fB-unixpw\fR above, however do not use -.IR su (1) -but rather -run the externally supplied command \fIcmd\fR. 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. -.IP -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. -.IP -If a list of allowed users is needed to limit who can -log in, use \fB-unixpw\fR [list] in addition to this option. -.IP -In FINDDISPLAY and FINDCREATEDISPLAY modes the \fIcmd\fR -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, -\fIcmd\fR 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"!) -.IP -#!/bin/sh -# Example x11vnc \fB-unixpw_cmd\fR script. -# Read the first two lines of stdin (user and passwd) -read user -read pass -.IP -debug=0 -if [ $debug = 1 ]; then -echo "user: $user" 1>&2 -echo "pass: $pass" 1>&2 -env | egrep \fB-i\fR 'rfb|vnc' 1>&2 -fi -.IP -# Check if the password is valid. -# (A real example would use ldap lookup, etc!) -if [ "X$pass" != "Xabc" ]; then -exit 1 # incorrect password -fi -.IP -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" \fB-c\fR "$RFB_UNIXPW_CMD_RUN" -fi -.IP -In \fB-unixpw_cmd\fR 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. -.PP -\fB-find\fR -.IP -Find the user's display using FINDDISPLAY. This -is an alias for "\fB-display\fR \fIWAIT:cmd=FINDDISPLAY\fR". -.IP -Note: if a \fB-display\fR occurs later on the command line -it will override the \fB-find\fR setting. -.IP -For this and the next few options see \fB-display\fR WAIT:... -below for all of the details. -.PP -\fB-finddpy\fR -.IP -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. -.PP -\fB-listdpy\fR -.IP -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. -.PP -\fB-findauth\fR \fI[disp]\fR -.IP -Apply the \fB-find/-finddpy\fR heuristics to try to guess -the XAUTHORITY file for DISPLAY 'disp'. If 'disp' -is not supplied, then the value in the \fB-display\fR on -the cmdline is used; failing that $DISPLAY is used; -and failing that ":0" is used. x11vnc then exits. -.IP -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. -.IP -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 \fB-env\fR FD_XDM=1 \fB-findauth\fR ... -(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 \fB-findauth\fR fails. -.PP -\fB-create\fR -.IP -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 -"\fB-display\fR \fIWAIT:cmd=FINDCREATEDISPLAY-Xvfb\fR". -.IP -Note: if a \fB-display\fR occurs later on the command line -it will override the \fB-create\fR setting. -.IP -SSH NOTE: for both \fB-find\fR and \fB-create\fR you can (should!) -add the "\fB-localhost\fR" option to force SSH tunnel access. -.PP -\fB-xdummy\fR -.IP -As in \fB-create,\fR except Xdummy instead of Xvfb. -.PP -\fB-xvnc\fR -.IP -As in \fB-create,\fR except Xvnc instead of Xvfb. -.PP -\fB-xvnc_redirect\fR -.IP -As in \fB-create,\fR except Xvnc.redirect instead of Xvfb. -.PP -\fB-xdummy_xvfb\fR -.IP -Sets WAIT:cmd=FINDCREATEDISPLAY-Xdummy,Xvfb -.PP -\fB-create_xsrv\fR \fIstr\fR -.IP -Sets WAIT:cmd=FINDCREATEDISPLAY-<str> Can be on cmdline -after anything that sets WAIT:.. and other things -(e.g. \fB-svc,\fR \fB-xdmsvc)\fR to adjust the X server list. -Example: \fB-svc\fR ... \fB-create_xsrv\fR Xdummy,X -.PP -\fB-svc\fR -.IP -Terminal services mode based on SSL access. Alias for -\fB-display\fR WAIT:cmd=FINDCREATEDISPLAY-Xvfb \fB-unixpw\fR \fB-users\fR -unixpw= \fB-ssl\fR SAVE Also "\fB-service\fR". -.IP -Note: if a \fB-display,\fR \fB-unixpw,\fR \fB-users,\fR or \fB-ssl\fR occurs -later on the command line it will override the \fB-svc\fR -setting. -.PP -\fB-svc_xdummy\fR -.IP -As \fB-svc\fR except Xdummy instead of Xvfb. -.PP -\fB-svc_xvnc\fR -.IP -As \fB-svc\fR except Xvnc instead of Xvfb. -.PP -\fB-svc_xdummy_xvfb\fR -.IP -As \fB-svc\fR with Xdummy,Xvfb. -.PP -\fB-xdmsvc\fR -.IP -Display manager Terminal services mode based on SSL. -Alias for \fB-display\fR WAIT:cmd=FINDCREATEDISPLAY-Xvfb.xdmcp -\fB-unixpw\fR \fB-users\fR unixpw= \fB-ssl\fR SAVE Also "\fB-xdm_service\fR". -.IP -Note: if a \fB-display,\fR \fB-unixpw,\fR \fB-users,\fR or \fB-ssl\fR occurs -later on the command line it will override the \fB-xdmsvc\fR -setting. -.IP -To create a session a user will have to first log in -to the \fB-unixpw\fR dialog and then log in again to the -XDM/GDM/KDM prompt. Subsequent re-connections will -only require the \fB-unixpw\fR password. See the discussion -under \fB-display\fR WAIT:... for more details about XDM, -etc configuration. -.IP -Remember to enable XDMCP in the xdm-config, gdm.conf, -or kdmrc configuration file. See \fB-display\fR WAIT: for -more info. -.PP -\fB-sshxdmsvc\fR -.IP -Display manager Terminal services mode based on SSH. -Alias for \fB-display\fR WAIT:cmd=FINDCREATEDISPLAY-Xvfb.xdmcp -\fB-localhost.\fR -.IP -The \fB-localhost\fR 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 \fB-display\fR WAIT:... for more details about XDM, -etc configuration. -.IP -Remember to enable XDMCP in the xdm-config, gdm.conf, -or kdmrc configuration file. See \fB-display\fR WAIT: for -more info. -.PP -\fB-unixpw_system_greeter\fR -.IP -Present a "Press 'Escape' for System Greeter" option -to the connecting VNC client in combined \fB-unixpw\fR -and xdmcp FINDCREATEDISPLAY modes (e.g. \fB-xdmsvc).\fR -.IP -Normally in a \fB-unixpw\fR mode the VNC client must -supply a valid username and password to gain access. -However, if \fB-unixpw_system_greeter\fR 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. -.IP -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 \fB-unixpw_system_greeter\fR option avoids the extra -password at X session creation time. -.IP -Example: x11vnc \fB-xdmsvc\fR \fB-unixpw_system_greeter\fR -See \fB-unixpw\fR and \fB-display\fR WAIT:... for more info. -.IP -The special options after a colon at the end of the -username (e.g. user:solid) described under \fB-display\fR -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. -.IP -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. -.IP -If the user pressed Escape the FINDCREATEDISPLAY command -will be run with the env. var. X11VNC_XDM_ONLY=1. -.IP -Remember to enable XDMCP in the xdm-config, gdm.conf, -or kdmrc configuration file. See \fB-display\fR WAIT: for -more info. -.PP -\fB-redirect\fR \fIport\fR -.IP -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. -.IP -If 0 <= port < 200 it is taken as a VNC display (5900 is -added to get the actual port), if port < 0 then \fB-port\fR -is used. -.IP -Probably the only reason to use the \fB-redirect\fR option -is in conjunction with SSL support, e.g. \fB-ssl\fR 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 "\fB-rfbport\fR \fIport1 \fB-ssl\fR SAVE \fB-redirect\fR host:port2\fR" -can act as a replacement for -.IR stunnel (1). -.IP -This mode only allows one redirected connection. -The \fB-forever\fR option does not apply. Use \fB-inetd\fR or -\fB-loop\fR for persistent service. -.PP -\fB-display\fR \fIWAIT:...\fR -.IP -A special usage mode for the normal \fB-display\fR option. -Useful with \fB-unixpw,\fR 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 \fB-rawfb\fR device). -.IP -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). -.IP -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. -.IP -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. -.IP -A more interesting case is like this: -.IP -WAIT:cmd=/usr/local/bin/find_display -.IP -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 -.IR 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; -.IP -xauth extract - $DISPLAY" -.IP -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 \fB-find\fR above) and FINDCREATEDISPLAY (alias \fB-create\fR -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 \fB-display\fR WAIT: modes. -.IP -In the case of \fB-unixpw\fR (and \fB-unixpw_nis\fR 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. -.IP -In the case of \fB-unixpw_cmd,\fR 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 -\fB-unixpw_cmd\fR option.) -.IP -Also in the case of \fB-unixpw,\fR 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, -.IP -login: fred:scale=3/4,sc=1,repeat -Password: ... -.IP -login: runge:sp=modem,rd=120,solid -.IP -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). -.IP -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. -.IP -In the login panel, press F1 to get a list of the -available options that you can add after the username. -.IP -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. -.IP -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. -.IP -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. -.IP -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 \fB-env\fR FD_USERPREFS=.x11vnc_create -and the user put "geom=1600x1200" in his -~/.x11vnc_create file. -.IP -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 \fB-gui\fR connect) or the remote control method -(x11vnc \fB-R\fR opt:val) during his VNC session. -.IP -So we see the combination of \fB-display\fR WAIT:cmd=... and -\fB-unixpw\fR 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. -.IP -A nice way to use WAIT:cmd=... is out of -.IR 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 -"\fB-users\fR \fIunixpw=\fR" 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. -.IP -BUILT-IN modes: -.IP -\fB--\fR Automatic Finding of User X Sessions \fB--\fR -.IP -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 -.IR who (1) -). -.IP -NOTE: The option "\fB-find\fR" is an alias for this mode. -.IP -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 "\fB-finddpy\fR" or WAIT:cmd=FINDDISPLAY-run -.IP -The standard script runs -.IR 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. -.IP -In \fB-find/cmd=FINDDISPLAY\fR mode, if you set FD_XDM=1, -e.g. 'x11vnc \fB-env\fR FD_XDM=1 \fB-find\fR ...' 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.) -.IP -As another special case, WAIT:cmd=HTTPONCE will allow -x11vnc to service one http request and then exit. -This is usually done in \fB-inetd\fR mode to run on, say, -port 5800 and allow the Java vncviewer to be downloaded -by client web browsers. For example: -.IP -5815 stream tcp nowait root /usr/sbin/tcpd /.../x11vnc \\ -\fB-inetd\fR \fB-q\fR \fB-http_ssl\fR \fB-prog\fR /.../x11vnc \\ -\fB-display\fR WAIT:cmd=HTTPONCE -.IP -Where /.../x11vnc is the full path to x11vnc. -It is used in the Apache SSL-portal example (see FAQ). -.IP -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.) -.IP -On some systems -.IR 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. -.IP -\fB--\fR Automatic Creation of User X Sessions \fB--\fR -.IP -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. -.IP -NOTE: The option "\fB-create\fR" is an alias for this mode. -.IP -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 -.IP -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 -.IP -By default FINDCREATEDISPLAY will try Xvfb and then -Xdummy: -.IP -The Xdummy wrapper is part of the x11vnc source code -(x11vnc/misc/Xdummy) It should be available in PATH -and have run "Xdummy \fB-install"\fR 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 \fB-root\fR to the Xdummy cmdline. -.IP -Xvfb is available on most platforms and does not -require root. -.IP -An advantage of Xdummy over Xvfb is that Xdummy supports -RANDR dynamic screen resizing. -.IP -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). -.IP -To troubleshoot the FINDCREATEDISPLAY mechanism, -set the following env. var. to an output log file, -e.g \fB-env\fR CREATE_DISPLAY_OUTPUT=/tmp/mydebug.txt -.IP -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, -.IR inetd (8) -to provide a means of -definitely getting a desktop (either real or virtual) -on the machine. E.g. a desktop service: -.IP -5900 stream tcp nowait root /usr/sbin/tcpd /.../x11vnc -\fB-inetd\fR \fB-q\fR \fB-http\fR \fB-ssl\fR SAVE \fB-unixpw\fR \fB-users\fR unixpw=\\ -\fB-passwd\fR secret \fB-prog\fR /.../x11vnc \\ -\fB-display\fR WAIT:cmd=FINDCREATEDISPLAY -.IP -Where /.../x11vnc is the full path to x11vnc. -.IP -See the \fB-svc/-service\fR option alias above. -.IP -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 \fB-env\fR ...) -This is the same as setting X11VNC_SKIP_DISPLAY=all or -supplying "nd=all" after "username:" -.IP -Use WAIT:cmd=FINDCREATEDISPLAY-print to print out the -script that is used for this. -.IP -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 -.IR xinit (1) -or -.IR startx (1). -If there is already an X server running -the X case may only work on Linux (see -.IR startx (1) -). -.IP -"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, -\fB-geometry,\fR and \fB-depth\fR and other X server options). -.IP -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. -.IP -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. -.IP -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. -.IP -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: -.IP -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 -.IP -See the shorthand options above "\fB-svc\fR", "\fB-xdmsvc\fR" -and "\fB-sshxdmsvc\fR" that specify the above options for -some useful cases. -.IP -If you set the env. var WAITBG=1 x11vnc will go into -the background once listening in wait mode. -.IP -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. -.IP -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. -.IP -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. -.PP -\fB-vencrypt\fR \fImode\fR -.IP -The VeNCrypt extension to the VNC protocol allows -encrypted SSL/TLS connections. If the \fB-ssl\fR 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.) -.IP -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 \fB-ssl\fR unless you set mode to "force". -.IP -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. -.IP -To disable all Anonymous Diffie-Hellman access -(susceptible to Man-In-The-Middle attack) you will need -to supply "\fB-vencrypt\fR \fInodh:support \fB-anontls\fR never\fR" -or "\fB-vencrypt\fR \fInodh:only\fR" -.IP -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 \fB-dhparams\fR -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. -.IP -Long example: \fB-vencrypt\fR newdh:nox509:support -.IP -Also, if mode is prefixed with "plain:", then -if \fB-unixpw\fR mode is active the VeNCrypt "*Plain" -username+passwd method is enabled for Unix logins. -Otherwise in \fB-unixpw\fR mode the normal login panel is -provided. -.IP -You *MUST* supply the \fB-ssl\fR option for VeNCrypt to -be active. The \fB-vencrypt\fR option only fine-tunes its -operation. -.PP -\fB-anontls\fR \fImode\fR -.IP -The ANONTLS extension to the VNC protocol allows -encrypted SSL/TLS connections. If the \fB-ssl\fR 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.) -.IP -ANONTLS is an older SSL/TLS mode introduced by vino. -.IP -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. -.IP -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 \fB-ssl\fR unless you set mode to "force". -.IP -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 \fB-dhparams\fR -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 \fB-vencrypt.\fR -.IP -Long example: \fB-anontls\fR newdh:plain:support -.IP -You *MUST* supply the \fB-ssl\fR option for ANONTLS to -be active. The \fB-anontls\fR option only fine-tunes its -operation. -.PP -\fB-sslonly\fR -.IP -Same as: "\fB-vencrypt\fR \fInever \fB-anontls\fR never\fR" i.e. it -disables the VeNCrypt and ANONTLS encryption methods -and only allows standard SSL tunneling. You must also -supply the \fB-ssl\fR ... option (see below.) -.PP -\fB-dhparams\fR \fIfile\fR -.IP -For some operations a set of Diffie Hellman parameters -(prime and generator) is needed. If so, use the -parameters in \fIfile\fR. 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 \fB-vencrypt\fR and \fB-anontls\fR -options to generate a new set each session. If that -is too slow for you, use \fB-dhparams\fR file to a set you -created manually via "openssl dhparam \fB-out\fR file 1024" -.PP -\fB-nossl\fR -.IP -Disable the \fB-ssl\fR option (see below). Since \fB-ssl\fR is off -by default \fB-nossl\fR would only be used on the commandline -to unset any *earlier* \fB-ssl\fR option (or \fB-svc...)\fR -.PP -\fB-ssl\fR \fI[pem]\fR -.IP -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 -\fB-ssl\fR is prescribed. See the \fB-stunnel\fR option below for -an alternative. -.IP -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 -\fB-httpdir\fR options.) The SSVNC viewer package supports -SSL tunnels too. -.IP -If the VNC Viewer supports VeNCrypt or ANONTLS (vino's -encryption mode) they are also supported by the \fB-ssl\fR -mode (see the \fB-vencrypt\fR and \fB-anontls\fR options for more -info; use \fB-sslonly\fR to disable both of them.) -.IP -Use "\fB-ssl\fR \fI/path/to/mycert.pem\fR" to specify an SSL -certificate file in PEM format to use to identify and -provide a key for this server. See -.IR openssl (1) -for more -info about PEMs and the \fB-sslGenCert\fR and "\fB-ssl\fR \fISAVE\fR" -options below for how to create them. -.IP -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 \fB-sslGenCA\fR 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. -.IP -If [pem] is empty or the string "SAVE" then the -.IR openssl (1) -command must be available to generate the -certificate the first time. A self-signed certificate -is generated (see \fB-sslGenCA\fR and \fB-sslGenCert\fR 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. -.IP -Use "SAVE_NOPROMPT" to avoid being prompted to -protect the generated key with a passphrase. However in -\fB-inetd\fR and \fB-bg\fR modes there will be no prompting for a -passphrase in either case. -.IP -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. -.IP -Use "SAVE-<string>" and "SAVE_PROMPT-<string>" -to refer to the file ~/.vnc/certs/server-<string>.pem -instead (it will be generated if it does not already -exist). E.g. "SAVE-charlie" will store to the file -~/.vnc/certs/server-charlie.pem -.IP -Examples: x11vnc \fB-ssl\fR SAVE \fB-display\fR :0 ... -x11vnc \fB-ssl\fR SAVE-someother \fB-display\fR :0 ... -.IP -If [pem] is "TMP" and the -.IR openssl (1) -utility -command exists in PATH, then a temporary, self-signed -certificate will be generated for this session. If -.IR openssl (1) -cannot be used to generate a temporary -certificate x11vnc exits immediately. The temporary -cert will be discarded when x11vnc exits. -.IP -If successful in using -.IR 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.) -.IP -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. -.IP -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. -.IP -See \fB-ssldir\fR below to use a directory besides the -default ~/.vnc/certs -.IP -If your x11vnc binary was not compiled with OpenSSL -library support, use of the \fB-ssl\fR option will induce an -immediate failure and exit. For such binaries, consider -using the \fB-stunnel\fR option for SSL encrypted connections. -.IP -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 "\fB-sslGenCert\fR" below. -.PP -\fB-ssltimeout\fR \fIn\fR -.IP -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. -.IP -Note that this value does NOT apply to the *initial* ssl -init connection. The default timeout for that is 20sec. -Use \fB-env\fR SSL_INIT_TIMEOUT=n to modify it. -.PP -\fB-sslnofail\fR -.IP -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. -.PP -\fB-ssldir\fR \fIdir\fR -.IP -Use \fIdir\fR as an alternate ssl certificate and key -management toplevel directory. The default is -~/.vnc/certs -.IP -This directory is used to store server and other -certificates and keys and also other materials. E.g. in -the simplest case, "\fB-ssl\fR \fISAVE\fR" will store the x11vnc -server cert in dir/server.pem -.IP -Use of alternate directories via \fB-ssldir\fR 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 -\fB-ssldir\fR /var/lib/x11vnc-certs). -.IP -\fB-ssldir\fR affects nearly all of the other \fB-ssl*\fR options, -e.g. \fB-ssl\fR SAVE, \fB-sslGenCert,\fR etc.. -.PP -\fB-sslverify\fR \fIpath\fR -.IP -For either of the \fB-ssl\fR or \fB-stunnel\fR modes, use \fIpath\fR -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. -.IP -If \fIpath\fR 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 -.IR stunnel (8) -manpage for details. -.IP -Examples: -x11vnc \fB-ssl\fR \fB-sslverify\fR ~/my.crt -x11vnc \fB-ssl\fR \fB-sslverify\fR ~/my_pem_dir/ -.IP -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 \fB-hash\fR \fB-noout\fR \fB-in\fR file.crt". Evidently -one uses <HASH>.1 if there is a collision... -.IP -The the key-management utility "\fB-sslCertInfo\fR \fIHASHON\fR" -and "\fB-sslCertInfo\fR \fIHASHOFF\fR" will create/delete these -hashes for you automatically (via symlink) in the HASH -subdirs it manages. Then you can point \fB-sslverify\fR to -the HASH subdir. -.IP -Special tokens: in \fB-ssl\fR mode, if \fIpath\fR is not a file or -a directory, it is taken as a comma separated list of -tokens that are interpreted as follows: -.IP -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. -.IP -Use \fB-ssldir\fR to use a directory different from the -~/.vnc/certs default. -.IP -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. -.IP -Examples: -x11vnc \fB-ssl\fR \fB-sslverify\fR CA -x11vnc \fB-ssl\fR \fB-sslverify\fR self:fred,self:jim -x11vnc \fB-ssl\fR \fB-sslverify\fR CA,clients -.IP -Usually "\fB-sslverify\fR \fICA\fR" is the most effective. -See the \fB-sslGenCA\fR and \fB-sslGenCert\fR options below for -how to set up and manage the CA framework. -.IP -NOTE: the following utilities, \fB-sslGenCA,\fR \fB-sslGenCert,\fR -\fB-sslEncKey,\fR \fB-sslCertInfo,\fR and \fB-sslCRL\fR are provided for -completeness, but for casual usage they are overkill. -.IP -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 -.IR openssl (1) -be installed on the system) -.IP -However, the simplest usage mode, "\fB-ssl\fR \fITMP\fR" (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. -.IP -To protect against Man-In-The-Middle attacks the "TMP" -mode can be improved by using "\fB-ssl\fR \fISAVE\fR" (same as -"\fB-ssl\fR", 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). -.IP -So keep in mind no CA key creation or management -(-sslGenCA and \fB-sslGenCert)\fR is needed for either of -the above two common usage modes. -.IP -One might want to use \fB-sslGenCA\fR and \fB-sslGenCert\fR -if you had a large number of VNC client and server -workstations. That way the administrator could generate -a single CA key with \fB-sslGenCA\fR and distribute its -certificate part to all of the workstations. -.IP -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. -.IP -Optionally, the admin could also make it so the -VNC clients themselves are authenticated to x11vnc -(-sslGenCert client ...) For this \fB-sslverify\fR would be -pointed to the CA cert (and/or self-signed certs). -.IP -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.) -.PP -\fB-sslCRL\fR \fIpath\fR -.IP -Set the Certificate Revocation Lists (CRL) to \fIpath\fR. -This setting applies for both \fB-ssl\fR and \fB-stunnel\fR modes. -.IP -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 -.IR stunnel (8) -documentation for -more info. -.IP -This option only applies if \fB-sslverify\fR has been -supplied: it checks for revocation along the -certificate chain used to verify the VNC client. -The \fB-sslCRL\fR setting will be ignored when \fB-sslverify\fR is -not specified. -.IP -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. -.IP -Only rarely will one's x11vnc \fB-ssl\fR infrastructure be so -large that this option would be useful (since normally -maintaining the contents of the \fB-sslverify\fR file or -directory should be enough.) However, when using -x11vnc with a Certificate Authority (see \fB-sslGenCA)\fR -to authenticate Clients via SSL/TLS, the \fB-sslCRL\fR 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. -.IP -To create a CRL file with revoked certificates the -commands 'openssl ca \fB-revoke\fR ...' and 'openssl ca -\fB-gencrl\fR ...' are useful. (Run them in ~/.vnc/certs) -.PP -\fB-sslGenCA\fR \fI[dir]\fR -.IP -Generate your own Certificate Authority private key, -certificate, and other files in directory [dir]. -x11vnc then exits. -.IP -If [dir] is not supplied, a \fB-ssldir\fR setting is used, -or otherwise ~/.vnc/certs is used. -.IP -This command also creates directories where server and -client certs and keys will be stored. The -.IR openssl (1) -program must be installed on the system and available -in PATH. -.IP -After the CA files and directories are created the -x11vnc command exits; the VNC server is not run. -.IP -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. -.IP -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 \fB-sslGenCert\fR option below. -.IP -Examples: -x11vnc \fB-sslGenCA\fR -x11vnc \fB-sslGenCA\fR ~/myCAdir -x11vnc \fB-ssldir\fR ~/myCAdir \fB-sslGenCA\fR -.IP -(the last two lines are equivalent) -.PP -\fB-sslGenCert\fR \fItype\fR \fIname\fR -.IP -Generate a VNC server or client certificate and private -key pair signed by the CA created previously with -\fB-sslGenCA.\fR The -.IR openssl (1) -program must be installed -on the system and available in PATH. -.IP -After the Certificate is generated x11vnc exits; the -VNC server is not run. -.IP -The type of key to be generated is the string \fItype\fR. -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). \fItype\fR is required. -.IP -An arbitrary default name you want to associate with -the key is supplied by the \fIname\fR string. You can -change it at the various prompts when creating the key. -\fIname\fR is optional. -.IP -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 "\fB-ssl\fR \fISAVE\fR" when the -server is started) -.IP -If \fIname\fR begins with the string "self:" then -a self-signed certificate is created instead of one -signed by your CA key. -.IP -If \fIname\fR 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. -.IP -The distinction between "server" and "client" is -simply the choice of output filenames and sub-directory. -This makes it so the \fB-ssl\fR SAVE-name option can easily -pick up the x11vnc PEM file this option generates. -And similarly makes it easy for the \fB-sslverify\fR option -to pick up your client certs. -.IP -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. -.IP -Precede this option with \fB-ssldir\fR [dir] to use a -directory other than the default ~/.vnc/certs You will -need to run \fB-sslGenCA\fR on that directory first before -doing any \fB-sslGenCert\fR key creation. -.IP -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. -.IP -Similar to \fB-sslGenCA,\fR you will be prompted to fill -in some information that will be recorded in the -certificate when it is created. -.IP -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. -.IP -You will also need to supply the CA private key -passphrase to unlock the private key created from -\fB-sslGenCA.\fR This private key is used to sign the server -or client certificate. -.IP -The "server" certs can be used by x11vnc directly by -pointing to them via the \fB-ssl\fR [pem] option. The default -file will be ~/.vnc/certs/server.pem. This one would -be used by simply typing \fB-ssl\fR SAVE. The pem file -contains both the certificate and the private key. -server.crt file contains the cert only. -.IP -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. -.IP -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. -.IP -Examples: -.IP -x11vnc \fB-sslGenCert\fR server -x11vnc \fB-ssl\fR SAVE \fB-display\fR :0 ... -.IP -and then on viewer using ss_vncviewer stunnel wrapper -(see the FAQ): -ss_vncviewer \fB-verify\fR ./cacert.crt hostname:0 -.IP -(this assumes the cacert.crt cert from \fB-sslGenCA\fR -was safely copied to the VNC viewer machine where -ss_vncviewer is run) -.IP -Example using a name: -.IP -x11vnc \fB-sslGenCert\fR server charlie -x11vnc \fB-ssl\fR SAVE-charlie \fB-display\fR :0 ... -.IP -Example for a client certificate (rarely used): -.IP -x11vnc \fB-sslGenCert\fR client roger -scp ~/.vnc/certs/clients/roger.pem somehost:. -rm ~/.vnc/certs/clients/roger.pem -.IP -x11vnc is then started with the option \fB-sslverify\fR -~/.vnc/certs/clients/roger.crt (or simply \fB-sslverify\fR -roger), and on the viewer user on somehost could do -for example: -.IP -ss_vncviewer \fB-mycert\fR ./roger.pem hostname:0 -.IP -If you set the env. var REQ_ARGS='...' it will be -passed to openssl -.IR req (1). -A common use would be -REQ_ARGS='-days 1095' to bump up the expiration date -(3 years in this case). -.PP -\fB-sslEncKey\fR \fIpem\fR -.IP -Utility to encrypt an existing PEM file with a -passphrase you supply when prompted. For that key to be -used (e.g. by x11vnc) the passphrase must be supplied -each time. -.IP -The "SAVE" notation described under \fB-ssl\fR applies as -well. (precede this option with \fB-ssldir\fR [dir] to refer -a directory besides the default ~/.vnc/certs) -.IP -The -.IR openssl (1) -program must be installed on the system -and available in PATH. After the Key file is encrypted -the x11vnc command exits; the VNC server is not run. -.IP -Examples: -x11vnc \fB-sslEncKey\fR /path/to/foo.pem -x11vnc \fB-sslEncKey\fR SAVE -x11vnc \fB-sslEncKey\fR SAVE-charlie -.PP -\fB-sslCertInfo\fR \fIpem\fR -.IP -Prints out information about an existing PEM file. -In addition the public certificate is also printed. -The -.IR openssl (1) -program must be in PATH. Basically the -command "openssl x509 \fB-text"\fR is run on the pem. -.IP -After the info is printed the x11vnc command exits; -the VNC server is not run. -.IP -The "SAVE" notation described under \fB-ssl\fR applies -as well. -.IP -Using "LIST" will give a list of all certs being -managed (in the ~/.vnc/certs dir, use \fB-ssldir\fR 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. \fB-sslCertInfo\fR charlie). Use "LISTL" or "LL" -for a long (ls \fB-l\fR style) listing. -.IP -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 \fB-ssldir.)\fR -This is a useful way for other OpenSSL applications -(e.g. stunnel) to access all of the certs without -having to concatenate them. x11vnc will not use them -unless you specifically reference them. "HASHOFF" -removes these HASH subdirs. -.IP -The LIST, LISTL, LL, ALL, HASHON, HASHOFF words can -also be lowercase, e.g. "list". -.PP -\fB-sslDelCert\fR \fIpem\fR -.IP -Prompts you to delete all .crt .pem .key .req files -associated with [pem]. x11vnc then exits. "SAVE" -and lookups as in \fB-sslCertInfo\fR apply as well. -.PP -\fB-sslScripts\fR -.IP -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. -.PP -\fB-stunnel\fR \fI[pem]\fR -.IP -Use the -.IR stunnel (8) -(stunnel.mirt.net) to provide an -encrypted SSL tunnel between viewers and x11vnc. -.IP -This external tunnel method was implemented prior to the -integrated \fB-ssl\fR encryption described above. It still -works well and avoids the requirement of linking with -the OpenSSL libraries. This mode requires stunnel -to be installed on the system and available via PATH -(n.b. stunnel is often installed in sbin directories). -Version 4.x of stunnel is assumed (but see \fB-stunnel3\fR -below.) -.IP -[pem] is optional, use "\fB-stunnel\fR \fI/path/to/stunnel.pem\fR" -to specify a PEM certificate file to pass to stunnel. -See the \fB-ssl\fR option for more info on certificate files. -.IP -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. -.IP -[pem] may also be the special strings "TMP", "SAVE", -and "SAVE..." as described in the \fB-ssl\fR option. -If [pem] is not supplied, "SAVE" is assumed. -.IP -Note that the VeNCrypt, ANONTLS, and "ANON" modes -are not supported in \fB-stunnel\fR mode. -.IP -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. -.IP -The \fB-localhost\fR option is enforced by default to avoid -people routing around the SSL channel. Use \fB-env\fR -STUNNEL_DISABLE_LOCALHOST=1 to disable this security -requirement. -.IP -Set \fB-env\fR STUNNEL_DEBUG=1 for more debugging printout. -.IP -Set \fB-env\fR STUNNEL_PROG=xxx to the full path of stunnel -program you want to be used (e.g. /usr/bin/stunnel4). -.IP -Set \fB-env\fR STUNNEL_LISTEN=xxx to the address of the -network interface to listen on (the default is to listen -on all interfaces), e.g. STUNNEL_LISTEN=192.168.1.100. -.IP -A simple way to add IPv6 support is STUNNEL_LISTEN=:: -.IP -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 \fB-ssl\fR option. -The x11vnc project's SSVNC is an option. -.IP -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 \fB-http,\fR \fB-http_ssl,\fR or -\fB-httpdir\fR (see the option descriptions for more info.) -.IP -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. -.IP -Currently the automatic "single port" HTTPS mode of -\fB-ssl\fR is not fully supported in \fB-stunnel\fR mode. However, -it can be emulated via: -.IP -% x11vnc \fB-stunnel\fR \fB-http_ssl\fR \fB-http_oneport\fR ... -.IP -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: -.IP -% stunnel \fB-c\fR \fB-d\fR localhost:5901 \fB-r\fR remotehost:5900 -% vncviewer localhost:1 -.IP -For Windows, stunnel has been ported to it and there -are probably other such tools available. See the FAQ -and SSVNC for more examples. -.PP -\fB-stunnel3\fR \fI[pem]\fR -.IP -Use version 3.x stunnel command line syntax instead of -version 4.x. The \fB-http/-httpdir\fR Java applet serving -is currently not available in this mode. -.PP -\fB-enc\fR \fIcipher:keyfile\fR -.IP -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. -.IP -NOTE: It is recommended that you use SSL via the \fB-ssl\fR -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. -.IP -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...) -.IP -cipher can be one of: arc4, aesv2, aes-cfb, blowfish, -aes256, or 3des. See the OpenSSL documentation for -more info. The keysize is 128 bits (except for aes256). -Here is one way to make a keyfile with that many bits: -.IP -dd if=/dev/random of=./my.key bs=16 count=1 -.IP -you will need to securely share this key with the other -side of the VNC connection (See SSVNC for examples). -.IP -Example: \fB-enc\fR blowfish:./my.key -Example: \fB-enc\fR blowfish:pw=swordfish -.IP -By default 16 bytes of random salt followed by 16 bytes -of random initialization vector are sent at the very -beginning of the stream. The other side must read these -and initialize their cipher with them. These values -make the session key unique (without them the security -is minimal). Similarly, the other side must send us -its random salt and IV with those same lengths. -.IP -The salt and key data are combined to create a session -key using an md5 hash as described in -.IR EVP_BytesToKey (3). -.IP -The exact call is: EVP_BytesToKey(Cipher, EVP_md5(), -salt, keydata, len, 1, keystr, NULL); where salt is -the random data as described above, and keydata is the -shared secret key data. keystr is the resulting session -key. The cipher is then seeded with keystr and uses -the random initialization vector as its first block. -.IP -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. -.IP -\fB-enc\fR aes-cfb@8,16:./my.key -.IP -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. -.IP -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. -.IP -\fB-enc\fR blowfish@-1,16:./my.key -.IP -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: -.IP -\fB-enc\fR arc4@sha+8,16:./my.key -.IP -The SSVNC vnc viewer project supplies a symmetric -encryption tool named "ultravnc_dsm_helper" that can -be used on the viewer side. For example: -.IP -ssvncviewer exec='ultravnc_dsm_helper arc4 my.key 0 h:p' -.IP -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. -.IP -Also see the 'Non-Ultra DSM' SSVNC option for the -\'UltraVNC DSM Encryption Plugin' advanced option. -.IP -For both ways of using the viewer, you can specify the -salt,ivec sizes (in GUI or, e.g. arc4@8,16). -.PP -\fB-https\fR \fI[port]\fR -.IP -Use a special, separate HTTPS port (-ssl and -\fB-stunnel\fR modes only) for HTTPS Java viewer applet -downloading. I.e. not 5900 and not 5800 (the defaults.) -.IP -BACKGROUND: In \fB-ssl\fR 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.: -.IP -https://mymachine.org:5900/ -.IP -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!) -.IP -END OF BACKGROUND. -.IP -USAGE: So use the \fB-https\fR option to provide a separate, -more reliable HTTPS port that x11vnc will listen on. If -[port] is not provided (or is 0), one is autoselected. -The URL to use is printed out at startup. -.IP -The SSL Java applet directory is specified via the -\fB-httpdir\fR option. If not supplied, \fB-https\fR will try -to guess the directory as though the \fB-http\fR option -was supplied. -.PP -\fB-httpsredir\fR \fI[port]\fR -.IP -In \fB-ssl\fR 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. -.IP -This is useful when an incoming TCP connection -redirection is performed by a router/gateway/firewall -from one port to an internal machine where x11vnc is -listening on a different port. The Java applet needs to -connect to the firewall/router port, not the VNC port -on the internal workstation. For example, one could -redir from mygateway.com:443 to workstation:5900. -.IP -This spares the user from having to type in -https://mygateway.com/?PORT=443 into their web -browser. Note that port 443 is the default https port; -other ports must be explicitly indicated, for example: -https://mygateway.com:8000/?PORT=8000. To avoid having -to include the PORT= in the browser URL, simply supply -"\fB-httpsredir\fR" to x11vnc. -.IP -This option does not work in \fB-stunnel\fR mode. -.IP -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 \fB-env\fR X11VNC_EXTRA_HTTPS_PARAMS='?GET=1' ... -.IP -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 \fB-env\fR X11VNC_HTTP_LISTEN_LOCALHOST=1 This way -the connection to the LibVNCServer httpd server will -only be available on localhost (note that in \fB-ssl\fR mode, -HTTPS requests are redirected from SSL to the non-SSL -LibVNCServer HTTP server.) -.PP -\fB-http_oneport\fR -.IP -For UN-encrypted connections mode (i.e. no \fB-ssl,\fR -\fB-stunnel,\fR or \fB-enc\fR options), allow the Java VNC Viewer -applet to be downloaded thru the VNC port via HTTP. -.IP -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: -.IP -http://hostname:5900 -.IP -The regular, two-port mode, URL http://hostname:5800 -will continue to work as well. -.IP -As mentioned above, this mode will NOT work with -the \fB-ssl,\fR \fB-stunnel,\fR or \fB-enc\fR 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.) -.IP -HTTPS single-port is on by default in \fB-ssl\fR encrypted -mode (and \fB-enc\fR too), so you only need \fB-http_oneport\fR -when doing non-SSL encrypted connections. -.IP -This mode could also be useful for SSH tunnels since -it means only one port needs to be redirected. -.IP -The \fB-httpsredir\fR option may also be useful for this -mode when using an SSH tunnel as well as for router -port redirections. -.IP -Note that the \fB-env\fR X11VNC_HTTP_LISTEN_LOCALHOST=1 -option described above under \fB-httpsredir\fR applies for -the LibVNCServer httpd server in all cases (ssl or not.) -.PP -\fB-ssh\fR \fIuser@host:disp\fR -.IP -Create a remote listening port on machine "host" -via a SSH tunnel using the \fB-R\fR 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 -.IP -This could be useful if a firewall/router prevents -incoming connections to the x11vnc machine, but -the ssh machine "host" can be reached by the VNC -viewer. "user@" is not needed unless the remote unix -username differs from the current one. -.IP -By default the remote sshd is usually configured to -listen only on localhost for rport, so the viewer may -need to ssh \fB-L\fR redir to "host" as well (See SSVNC to -automate this). The sshd setting GatewayPorts enables -listening on all interfaces for rport; viewers can -reach it more easily. -.IP -"disp" is the VNC display for the remote SSH side, -e.g. 0 corresponds to port 5900, etc. If disp is -greater than 200 the value is used as the port. Use a -negative value to force a low port, e.g. host:-80 will -use port 80. -.IP -If ssh-agent is not active, then the ssh password needs -to be entered in the terminal where x11vnc is running. -.IP -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. -.IP -If the remote SSH server is on a non-standard port -(i.e. not 22) use user@host:port:disp+secs. -.IP -Note that the ssh process MAY NOT be killed when -x11vnc exits. It tries by looking at -.IR ps (1) -output. -.PP -\fB-usepw\fR -.IP -If no other password method was supplied on the command -line, first look for ~/.vnc/passwd and if found use it -with \fB-rfbauth;\fR next, look for ~/.vnc/passwdfile and -use it with \fB-passwdfile;\fR otherwise, prompt the user -for a password to create ~/.vnc/passwd and use it with -the \fB-rfbauth\fR option. If none of these succeed x11vnc -exits immediately. -.PP -\fB-storepasswd\fR \fIpass\fR \fIfile\fR -.IP -Store password \fIpass\fR as the VNC password in the -file \fIfile\fR. Once the password is stored the -program exits. Use the password via "\fB-rfbauth\fR \fIfile\fR" -.IP -If called with no arguments, "x11vnc \fB-storepasswd",\fR -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. -.PP -\fB-nopw\fR -.IP -Disable the big warning message when you use x11vnc -without some sort of password. -.PP -\fB-accept\fR \fIstring\fR -.IP -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. \fIstring\fR is -an external command run via -.IR system (3) -or some special -cases described below. Be sure to quote \fIstring\fR -if it contains spaces, shell characters, etc. If the -external command returns 0 the client is accepted, -otherwise the client is rejected. See below for an -extension to accept a client view-only. -.IP -If x11vnc is running as root (say from -.IR inetd (8) -or from -display managers -.IR xdm (1) -, -.IR gdm (1) -, etc), think about the -security implications carefully before supplying this -option (likewise for the \fB-gone\fR option). -.IP -Environment: The RFB_CLIENT_IP environment variable will -be set to the incoming client IP number and the port -in RFB_CLIENT_PORT (or -1 if unavailable). Similarly, -RFB_SERVER_IP and RFB_SERVER_PORT (the x11vnc side -of the connection), are set to allow identification -of the tcp virtual circuit. The x11vnc process -id will be in RFB_X11VNC_PID, a client id number in -RFB_CLIENT_ID, and the number of other connected clients -in RFB_CLIENT_COUNT. RFB_MODE will be "accept". -RFB_STATE will be PROTOCOL_VERSION, SECURITY_TYPE, -AUTHENTICATION, INITIALISATION, NORMAL, or UNKNOWN -indicating up to which state the client has achieved. -RFB_LOGIN_VIEWONLY will be 0, 1, or -1 (unknown). -RFB_USERNAME, RFB_LOGIN_TIME, and RFB_CURRENT_TIME may -also be set. -.IP -If \fIstring\fR 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). -.IP -In the case of "popup" and when the \fB-unixpw\fR option -is specified, then a *second* window will be popped -up after the user successfully logs in via his UNIX -password. This time the user will be identified as -UNIX:username@hostname, the "UNIX:" prefix indicates -which user the viewer logged as via \fB-unixpw.\fR The first -popup is only for whether to allow him to even *try* -to login via unix password. -.IP -If \fIstring\fR is "xmessage" then an -.IR xmessage (1) -invocation is used for the command. xmessage must be -installed on the machine for this to work. -.IP -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 -\fB-viewonly\fR has been specified, in which case the entire -display is view only. -.IP -If the user supplied command is prefixed with something -like "yes:0,no:*,view:3 mycommand ..." then this -associates the numerical command return code with -the actions: accept, reject, and accept-view-only, -respectively. Use "*" instead of a number to indicate -the default action (in case the command returns an -unexpected value). E.g. "no:*" is a good choice. -.IP -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). -.IP -More \fB-accept\fR 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. -.PP -\fB-afteraccept\fR \fIstring\fR -.IP -As \fB-accept,\fR 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 \fB-accept.\fR Unlike \fB-accept,\fR the -command return code is not interpreted by x11vnc. -Example: \fB-afteraccept\fR 'killall xlock &' -.PP -\fB-gone\fR \fIstring\fR -.IP -As \fB-accept,\fR 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 \fB-accept.\fR The "popup" actions apply as well. -Unlike \fB-accept,\fR the command return code is not -interpreted by x11vnc. Example: \fB-gone\fR 'xlock &' -.PP -\fB-users\fR \fIlist\fR -.IP -If x11vnc is started as root (say from -.IR inetd (8) -or from -display managers -.IR xdm (1) -, -.IR 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 \fIlist\fR. If x11vnc is not running as -root this option is ignored. -.IP -Why use this option? In general it is not needed since -x11vnc is already connected to the X display and can -perform its primary functions. The option was added -to make some of the *external* utility commands x11vnc -occasionally runs work properly. In particular under -GNOME and KDE to implement the "\fB-solid\fR \fIcolor\fR" feature -external commands (gconftool-2 and dcop) unfortunately -must be run as the user owning the desktop session. -Since this option switches userid it also affects the -userid used to run the processes for the \fB-accept\fR and -\fB-gone\fR options. It also affects the ability to read -files for options such as \fB-connect,\fR \fB-allow,\fR and \fB-remap\fR -and also the ultra and tight filetransfer feature if -enabled. Note that the \fB-connect\fR file is also sometimes -written to. -.IP -So be careful with this option since in some situations -its use can decrease security. -.IP -In general the switch to a user will only take place -if the display can still be successfully opened as that -user (this is primarily to try to guess the actual owner -of the session). Example: "\fB-users\fR \fIfred,wilma,betty\fR". -Note that a malicious local user "barney" by -quickly using "xhost +" when logging in may possibly -get the x11vnc process to switch to user "fred". -What happens next? -.IP -Under display managers it may be a long time before -the switch succeeds (i.e. a user logs in). To instead -make it switch immediately regardless if the display -can be reopened prefix the username with the "+" -character. E.g. "\fB-users\fR \fI+bob\fR" or "\fB-users\fR \fI+nobody\fR". -.IP -The latter (i.e. switching immediately to user -"nobody") is the only obvious use of the \fB-users\fR option -that increases security. -.IP -Use the following notation to associate a group with -a user: user1.group1,user2.group2,... Note that -.IR initgroups (2) -will still be called first to try to -switch to ALL of a user's groups (primary and additional -groups). Only if that fails or it is not available -then the single group specified as above (or the user's -primary group if not specified) is switched to with -.IR setgid (2). -Use \fB-env\fR X11VNC_SINGLE_GROUP=1 to prevent -trying -.IR 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. -.IP -In \fB-unixpw\fR mode, if "\fB-users\fR \fIunixpw=\fR" is supplied -then after a user authenticates himself via the -\fB-unixpw\fR mechanism, x11vnc will try to switch to that -user as though "\fB-users\fR \fI+username\fR" had been supplied. -If you want to limit which users this will be done for, -provide them as a comma separated list after "unixpw=" -Groups can also be specified as described above. -.IP -Similarly, in \fB-ssl\fR mode, if "\fB-users\fR \fIsslpeer=\fR" is -supplied then after an SSL client authenticates with his -cert (the \fB-sslverify\fR option is required for this) x11vnc -will extract a UNIX username from the "emailAddress" -field (username@hostname.com) of the "Subject" of the -x509 SSL cert and then try to switch to that user as -though "\fB-users\fR \fI+username\fR" had been supplied. If you -want to limit which users this will be done for, provide -them as a comma separated list after "sslpeer=". -Set the env. var X11VNC_SSLPEER_CN to use the Common -Name (normally a hostname) instead of the Email field. -.IP -NOTE: for sslpeer= mode the x11vnc administrator must -take care that any client certs he adds to \fB-sslverify\fR -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 \fB-text\fR \fB-in\fR file.crt", see the -"Subject:" line. Also, along with the normal RFB_* -env. vars. (see \fB-accept)\fR passed to external cmd= -commands, RFB_SSL_CLIENT_CERT will be set to the -client's x509 certificate string. -.IP -The sslpeer= mode can aid finding X sessions via the -FINDDISPLAY and FINDCREATEDISPLAY mechanisms. -.IP -To immediately switch to a user *before* connections -to the X display are made or any files opened use the -"=" character: "\fB-users\fR \fI=bob\fR". That user needs to -be able to open the X display and any files of course. -.IP -The special user "guess=" means to examine the utmpx -database (see -.IR who (1) -) looking for a user attached to -the display number (from DISPLAY or \fB-display\fR option) -and try him/her. To limit the list of guesses, use: -"\fB-users\fR \fIguess=bob,betty\fR". -.IP -Even more sinister is the special user "lurk=" -that means to try to guess the DISPLAY from the utmpx -login database as well. So it "lurks" waiting for -anyone to log into an X session and then connects to it. -Specify a list of users after the = to limit which users -will be tried. To enable a different searching mode, if -the first user in the list is something like ":0" or -":0-2" that indicates a range of DISPLAY numbers that -will be tried (regardless of whether they are in the -utmpx database) for all users that are logged in. Also -see the "\fB-display\fR \fIWAIT:...\fR" functionality. Examples: -"\fB-users\fR \fIlurk=\fR" and also "\fB-users\fR \fIlurk=:0-1,bob,mary\fR" -.IP -Be especially careful using the "guess=" and "lurk=" -modes. They are not recommended for use on machines -with untrustworthy local users. -.PP -\fB-noshm\fR -.IP -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 \fB-onetile\fR is not sufficient. -.PP -\fB-flipbyteorder\fR -.IP -Sometimes needed if remotely polled host has different -endianness. Ignored unless \fB-noshm\fR is set. -.PP -\fB-onetile\fR -.IP -Do not use the new copy_tiles() framebuffer mechanism, -just use 1 shm tile for polling. Limits shm segments -used to 3. -.IP -To disable any automatic shm reduction set the -env. var. X11VNC_NO_LIMIT_SHM. -.PP -\fB-solid\fR \fI[color]\fR -.IP -To improve performance, when VNC clients are connected -try to change the desktop background to a solid color. -The [color] is optional: the default color is "cyan4". -For a different one specify the X color (rgb.txt name, -e.g. "darkblue" or numerical "#RRGGBB"). -.IP -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 ( -.IR inetd (8) -or -.IR gdm (1) -), -the \fB-users\fR option may be needed for GNOME, KDE, XFCE. -If x11vnc guesses your desktop incorrectly, you can -force it by prefixing color with "gnome:", "kde:", -"cde:", "xfce:", or "root:". -.IP -Update: \fB-solid\fR no longer works on KDE4. -.IP -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. -.PP -\fB-blackout\fR \fIstring\fR -.IP -Black out rectangles on the screen. \fIstring\fR 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. -.PP -\fB-xinerama,\fR \fB-noxinerama\fR -.IP -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: \fB-xinerama\fR -.IP -In general, we have noticed on XINERAMA displays you may -need to use the "\fB-xwarppointer\fR" option if the mouse -pointer misbehaves and it is enabled by default. Use -"\fB-noxwarppointer\fR" if you do not want this. -.PP -\fB-xtrap\fR -.IP -Use the DEC-XTRAP extension for keystroke and mouse -input insertion. For use on legacy systems, e.g. X11R5, -running an incomplete or missing XTEST extension. -By default DEC-XTRAP will be used if XTEST server grab -control is missing, use \fB-xtrap\fR to do the keystroke and -mouse insertion via DEC-XTRAP as well. -.PP -\fB-xrandr\fR \fI[mode]\fR -.IP -If the display supports the XRANDR (X Resize, Rotate -and Reflection) extension, and you expect XRANDR events -to occur to the display while x11vnc is running, this -options indicates x11vnc should try to respond to -them (as opposed to simply crashing by assuming the -old screen size). See the -.IR xrandr (1) -manpage and run -\'xrandr \fB-q'\fR for more info. [mode] is optional and -described below. -.IP -Since watching for XRANDR events and trapping errors -increases polling overhead, only use this option if -XRANDR changes are expected. For example on a rotatable -screen PDA or laptop, or using a XRANDR-aware Desktop -where you resize often. It is best to be viewing with a -vncviewer that supports the NewFBSize encoding, since it -knows how to react to screen size changes. Otherwise, -LibVNCServer tries to do so something reasonable for -viewers that cannot do this (portions of the screen -may be clipped, unused, etc). -.IP -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 \fB-xrandr\fR mode -is enabled. To disable even checking for events supply: -\fB-noxrandr.\fR -.IP -"mode" defaults to "resize", which means create a -new, resized, framebuffer and hope all viewers can cope -with the change. "newfbsize" means first disconnect -all viewers that do not support the NewFBSize VNC -encoding, and then resize the framebuffer. "exit" -means disconnect all viewer clients, and then terminate -x11vnc. -.PP -\fB-rotate\fR \fIstring\fR -.IP -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. \fIstring\fR can be: -.IP -x flip along x-axis -y flip along y-axis -xy flip along x- and y-axes -+90 rotate 90 degrees clockwise -\fB-90\fR rotate 90 degrees counter-clockwise -+90x rotate 90 degrees CW, then flip along x -+90y rotate 90 degrees CW, then flip along y -.IP -these give all possible rotations and reflections. -.IP -Aliases: same as xy: yx, +180, \fB-180,\fR 180 -same as \fB-90:\fR +270, 270 -same as +90: 90, (ditto for 90x, 90y) -.IP -Like \fB-scale,\fR this transformation is applied at the very -end of any chain of framebuffer transformations and so -any options with geometries, e.g. \fB-blackout,\fR \fB-clip,\fR etc. -are relative to the original X (or \fB-rawfb)\fR framebuffer, -not the final one sent to VNC viewers. -.IP -If you do not want the cursor shape to be rotated -prefix \fIstring\fR with "nc:", e.g. "nc:+90", -"nc:xy", etc. -.PP -\fB-padgeom\fR \fIWxH\fR -.IP -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 \fB-xrandr,\fR -\fB-remote\fR id:windowid, rescaling, etc.) -.IP -In \fB-unixpw\fR mode this sets the size of the login screen. -Use "once:WxH" it ignore padgeom after the login -screen is set up. -.PP -\fB-o\fR \fIlogfile\fR -.IP -Write stderr messages to file \fIlogfile\fR instead of to -the terminal. Same as "\fB-logfile\fR \fIfile\fR". To append -to the file use "\fB-oa\fR \fIfile\fR" or "\fB-logappend\fR \fIfile\fR". -If \fIlogfile\fR contains the string "%VNCDISPLAY" -it is expanded to the vnc display (the name may need -to be guessed at.) "%HOME" works too. -.PP -\fB-flag\fR \fIfile\fR -.IP -Write the "PORT=NNNN" (e.g. PORT=5900) string to -\fIfile\fR in addition to stdout. This option could be -useful by wrapper script to detect when x11vnc is ready. -.PP -\fB-rmflag\fR \fIfile\fR -.IP -Remove \fIfile\fR at exit to signal when x11vnc is done. -The file is created at startup if it does not already -exist or if \fIfile\fR is prefixed with "create:". -If the file is created, the x11vnc PID is placed in -the file. Otherwise the files contents is not changed. -Use prefix "nocreate:" to prevent creation. -.PP -\fB-rc\fR \fIfilename\fR -.IP -Use \fIfilename\fR instead of $HOME/.x11vncrc for rc file. -.PP -\fB-norc\fR -.IP -Do not process any .x11vncrc file for options. -.PP -\fB-env\fR \fIVAR=VALUE\fR -.IP -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. -.PP -\fB-prog\fR \fI/path/to/x11vnc\fR -.IP -Set the full path to the x11vnc program for cases when -it cannot be determined from argv[0] (e.g. tcpd/inetd) -.PP -\fB-h,\fR \fB-help\fR -.IP -Print this help text. --?, \fB-opts\fR Only list the x11vnc options. -.PP -\fB-V,\fR \fB-version\fR -.IP -Print program version and last modification date. -.PP -\fB-license\fR -.IP -Print out license information. Same as \fB-copying\fR and -\fB-warranty.\fR -.PP -\fB-dbg\fR -.IP -Instead of exiting after cleaning up, run a simple -"debug crash shell" when fatal errors are trapped. -.PP -\fB-q,\fR \fB-quiet\fR -.IP -Be quiet by printing less informational output to -stderr. (use \fB-noquiet\fR to undo an earlier \fB-quiet.)\fR -.IP -The \fB-quiet\fR option does not eliminate all informational -output, it only reduces it. It is ignored in most -auxiliary usage modes, e.g. \fB-storepasswd.\fR To eliminate -all output use: 2>/dev/null 1>&2, etc. -.PP -\fB-v,\fR \fB-verbose\fR -.IP -Print out more information to stderr. -.PP -\fB-bg\fR -.IP -Go into the background after screen setup. Messages to -stderr are lost unless \fB-o\fR logfile is used. Something -like this could be useful in a script: -.IP -port=`ssh -t $host "x11vnc -display :0 -bg" | grep PORT` -.IP -port=`echo "$port" | sed -e 's/PORT=//'` -.IP -port=`expr $port - 5900` -.IP -vncviewer $host:$port -.PP -\fB-modtweak,\fR \fB-nomodtweak\fR -.IP -Option \fB-modtweak\fR 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: \fB-modtweak\fR -.IP -If you are having trouble with with keys and \fB-xkb\fR or -\fB-noxkb,\fR and similar things don't help, try \fB-nomodtweak.\fR -.IP -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 \fB-pk"\fR or the \fB-dk\fR option. The failure -is when you try to type "#" it yields "3". If you -see this problem try setting the environment variable -MODTWEAK_LOWEST=1 to see if it helps. -.PP -\fB-xkb,\fR \fB-noxkb\fR -.IP -When in modtweak mode, use the XKEYBOARD extension (if -the X display supports it) to do the modifier tweaking. -This is powerful and should be tried if there are still -keymapping problems when using \fB-modtweak\fR by itself. -The default is to check whether some common keysyms, -e.g. !, @, [, are only accessible via \fB-xkb\fR mode and if -so then automatically enable the mode. To disable this -automatic detection use \fB-noxkb.\fR -.IP -When \fB-xkb\fR mode is active you can set these env. vars. -They apply only when there is ambiguity as to which -key to choose (i.e the mapping is not one-to-one). -NOKEYHINTS=1: for up ascii keystrokes do not use score -hints saved when the key was pressed down. NOANYDOWN=1: -for up keystrokes do not resort to searching through -keys that are currently pressed down. KEYSDOWN=N: -remember the last N keys press down for tie-breaking -when an up keystroke comes in. -.PP -\fB-capslock\fR -.IP -When in \fB-modtweak\fR (the default) or \fB-xkb\fR mode, -if a keysym in the range A-Z comes in check the X -server to see if the Caps_Lock is set. If it is do -not artificially press Shift to generate the keysym. -This will enable the CapsLock key to behave correctly -in some circumstances: namely *both* the VNC viewer -machine and the x11vnc X server are in the CapsLock -on state. If one side has CapsLock on and the other -off and the keyboard is not behaving as you think it -should you should correct the CapsLock states (hint: -pressing CapsLock inside and outside of the viewer can -help toggle them both to the correct state). However, -for best results do not use this option, but rather -*only* enable CapsLock on the VNC viewer side (i.e. by -pressing CapsLock outside of the viewer window, also -\fB-skip_lockkeys\fR below). Also try \fB-nomodtweak\fR for a -possible workaround. -.PP -\fB-skip_lockkeys,\fR \fB-noskip_lockkeys\fR -.IP -Have x11vnc ignore all Caps_Lock, Shift_Lock, Num_Lock, -Scroll_Lock keysyms received from viewers. The idea is -you press Caps_Lock on the VNC Viewer side but that does -not change the lock state in the x11vnc-side X server. -Nevertheless your capitalized letters come in over -the wire and are applied correctly to the x11vnc-side -X server. Note this mode probably won't do what you -want in \fB-nomodtweak\fR mode. Also, a kludge for KP_n -digits is always done in this mode: they are mapped to -regular digit keysyms. See also \fB-capslock\fR above. -The default is \fB-noskip_lockkeys.\fR -.PP -\fB-skip_keycodes\fR \fIstring\fR -.IP -Ignore the comma separated list of decimal keycodes. -Perhaps these are keycodes not on your keyboard but -your X server thinks exist. Currently only applies -to \fB-xkb\fR mode. Use this option to help x11vnc in the -reverse problem it tries to solve: Keysym -> Keycode(s) -when ambiguities exist (more than one Keycode per -Keysym). Run 'xmodmap \fB-pk'\fR to see your keymapping. -Example: "\fB-skip_keycodes\fR \fI94,114\fR" -.PP -\fB-sloppy_keys\fR -.IP -Experimental option that tries to correct some -"sloppy" key behavior. E.g. if at the viewer you -press Shift+Key but then release the Shift before -Key that could give rise to extra unwanted characters -(usually only between keyboards of different languages). -Only use this option if you observe problems with -some keystrokes. -.PP -\fB-skip_dups,\fR \fB-noskip_dups\fR -.IP -Some VNC viewers send impossible repeated key events, -e.g. key-down, key-down, key-up, key-up all for the same -key, or 20 downs in a row for the same modifier key! -Setting \fB-skip_dups\fR means to skip these duplicates and -just process the first event. Note: some VNC viewers -assume they can send down's without the corresponding -up's and so you should not set this option for -these viewers (symptom: some keys do not autorepeat) -Default: \fB-noskip_dups\fR -.PP -\fB-add_keysyms,\fR \fB-noadd_keysyms\fR -.IP -If a Keysym is received from a VNC viewer and that -Keysym does not exist in the X server, then add the -Keysym to the X server's keyboard mapping on an unused -key. Added Keysyms will be removed periodically and -also when x11vnc exits. Default: \fB-add_keysyms\fR -.PP -\fB-clear_mods\fR -.IP -At startup and exit clear the modifier keys by sending -KeyRelease for each one. The Lock modifiers are skipped. -Used to clear the state if the display was accidentally -left with any pressed down. -.PP -\fB-clear_keys\fR -.IP -As \fB-clear_mods,\fR except try to release ANY pressed key. -Note that this option and \fB-clear_mods\fR can interfere -with a person typing at the physical keyboard. -.PP -\fB-clear_all\fR -.IP -As \fB-clear_keys,\fR except try to release any CapsLock, -NumLock, etc. locks as well. -.PP -\fB-remap\fR \fIstring\fR -.IP -Read Keysym remappings from file named \fIstring\fR. -Format is one pair of Keysyms per line (can be name -or hex value) separated by a space. If no file named -\fIstring\fR exists, it is instead interpreted as this -form: key1-key2,key3-key4,... See <X11/keysymdef.h> -header file for a list of Keysym names, or use -.IR xev (1). -.IP -To map a key to a button click, use the fake Keysyms -"Button1", ..., etc. E.g: "\fB-remap\fR \fISuper_R-Button2\fR" -(useful for pasting on a laptop) -.IP -I use these if the machine I am viewing from does not -have a scrollwheel or I don't like using the one it has: -.IP -\fB-remap\fR Super_R-Button4,Menu-Button5 -\fB-remap\fR KP_Add-Button4,KP_Enter-Button5 -.IP -the former would be used on a PC, the latter on a -MacBook. This way those little used keys can be used -to generate bigger hops than the Up and Down arrows -provide. One can scroll through text or web pages more -quickly this way (especially if x11vnc scroll detection -is active.) -.IP -Use Button44, Button12, etc. for multiple clicks. -.IP -To disable a keysym (i.e. make it so it will not be -injected), remap it to "NoSymbol" or "None". -.IP -Dead keys: "dead" (or silent, mute) keys are keys that -do not produce a character but must be followed by a 2nd -keystroke. This is often used for accenting characters, -e.g. to put "`" on top of "a" by pressing the dead -key and then "a". Note that this interpretation -is not part of core X11, it is up to the toolkit or -application to decide how to react to the sequence. -The X11 names for these keysyms are "dead_grave", -"dead_acute", etc. However some VNC viewers send the -keysyms "grave", "acute" instead thereby disabling -the accenting. To work around this \fB-remap\fR can be used. -For example "\fB-remap\fR \fIgrave-dead_grave,acute-dead_acute\fR" -.IP -As a convenience, "\fB-remap\fR \fIDEAD\fR" applies these remaps: -.IP - g grave-dead_grave - a acute-dead_acute - c asciicircum-dead_circumflex - t asciitilde-dead_tilde - m macron-dead_macron - b breve-dead_breve - D abovedot-dead_abovedot - d diaeresis-dead_diaeresis - o degree-dead_abovering - A doubleacute-dead_doubleacute - r caron-dead_caron - e cedilla-dead_cedilla -.IP -.IP -If you just want a subset use the first letter -label, e.g. "\fB-remap\fR \fIDEAD=ga\fR" to get the first two. -Additional remaps may also be supplied via commas, -e.g. "\fB-remap\fR \fIDEAD=ga,Super_R-Button2\fR". Finally, -"DEAD=missing" means to apply all of the above as -long as the left hand member is not already in the -X11 keymap. -.PP -\fB-norepeat,\fR \fB-repeat\fR -.IP -Option \fB-norepeat\fR disables X server key auto repeat when -VNC clients are connected and VNC keyboard input is -not idle for more than 5 minutes. This works around a -repeating keystrokes bug (triggered by long processing -delays between key down and key up client events: -either from large screen changes or high latency). -Default: \fB-norepeat\fR -.IP -You can set the env. var. X11VNC_IDLE_TIMEOUT to the -number of idle seconds you want (5min = 300secs). -.IP -Note: your VNC viewer side will likely do autorepeating, -so this is no loss unless someone is simultaneously at -the real X display. -.IP -Use "\fB-norepeat\fR \fIN\fR" to set how many times norepeat will -be reset if something else (e.g. X session manager) -undoes it. The default is 2. Use a negative value -for unlimited resets. -.PP -\fB-nofb\fR -.IP -Ignore video framebuffer: only process keyboard and -pointer. Intended for use with Win2VNC and x2vnc -dual-monitor setups. -.PP -\fB-nobell\fR -.IP -Do not watch for XBell events. (no beeps will be heard) -Note: XBell monitoring requires the XKEYBOARD extension. -.PP -\fB-nosel\fR -.IP -Do not manage exchange of X selection/cutbuffer between -VNC viewers and the X server at all. -.PP -\fB-noprimary\fR -.IP -Do not poll the PRIMARY selection for changes to send -back to clients. (PRIMARY is still set on received -changes, however). -.PP -\fB-nosetprimary\fR -.IP -Do not set the PRIMARY selection for changes received -from VNC clients. -.PP -\fB-noclipboard\fR -.IP -Do not poll the CLIPBOARD selection for changes to send -back to clients. (CLIPBOARD is still set on received -changes, however). -.PP -\fB-nosetclipboard\fR -.IP -Do not set the CLIPBOARD selection for changes -received from VNC clients. -.PP -\fB-seldir\fR \fIstring\fR -.IP -If direction string is "send", only send the selection -to viewers, and if it is "recv" only receive it from -viewers. To work around apps setting the selection -too frequently and messing up the other end. You can -actually supply a comma separated list of directions, -including "debug" to turn on debugging output. -.PP -\fB-cursor\fR \fI[mode],\fR \fB-nocursor\fR -.IP -Sets how the pointer cursor shape (little icon at the -mouse pointer) should be handled. The "mode" string -is optional and is described below. The default -is to show some sort of cursor shape(s). How this -is done depends on the VNC viewer and the X server. -Use \fB-nocursor\fR to disable cursor shapes completely. -.IP -Some VNC viewers support the TightVNC CursorPosUpdates -and CursorShapeUpdates extensions (cuts down on -network traffic by not having to send the cursor image -every time the pointer is moved), in which case these -extensions are used (see \fB-nocursorshape\fR and \fB-nocursorpos\fR -below to disable). For other viewers the cursor shape -is written directly to the framebuffer every time the -pointer is moved or changed and gets sent along with -the other framebuffer updates. In this case, there -will be some lag between the vnc viewer pointer and -the remote cursor position. -.IP -If the X display supports retrieving the cursor shape -information from the X server, then the default is -to use that mode. On Solaris this can be done with -the SUN_OVL extension using \fB-overlay\fR (see also the -\fB-overlay_nocursor\fR option). A similar overlay scheme -is used on IRIX. Xorg (e.g. Linux) and recent Solaris -Xsun servers support the XFIXES extension to retrieve -the exact cursor shape from the X server. If XFIXES -is present it is preferred over Overlay and is used by -default (see \fB-noxfixes\fR below). This can be disabled -with \fB-nocursor,\fR and also some values of the "mode" -option below. -.IP -Note that under XFIXES cursors with transparency (alpha -channel) will usually not be exactly represented and one -may find Overlay preferable. See also the \fB-alphacut\fR -and \fB-alphafrac\fR options below as fudge factors to try -to improve the situation for cursors with transparency -for a given theme. -.IP -The "mode" string can be used to fine-tune the -displaying of cursor shapes. It can be used the -following ways: -.IP -"\fB-cursor\fR \fIarrow\fR" - just show the standard arrow -nothing more or nothing less. -.IP -"\fB-cursor\fR \fInone\fR" - same as "\fB-nocursor\fR" -.IP -"\fB-cursor\fR \fIX\fR" - when the cursor appears to be on the -root window, draw the familiar X shape. Some desktops -such as GNOME cover up the root window completely, -and so this will not work, try "X1", etc, to try to -shift the tree depth. On high latency links or slow -machines there will be a time lag between expected and -the actual cursor shape. -.IP -"\fB-cursor\fR \fIsome\fR" - like "X" but use additional -heuristics to try to guess if the window should have -a windowmanager-like resizer cursor or a text input -I-beam cursor. This is a complete hack, but may be -useful in some situations because it provides a little -more feedback about the cursor shape. -.IP -"\fB-cursor\fR \fImost\fR" - try to show as many cursors as -possible. Often this will only be the same as "some" -unless the display has overlay visuals or XFIXES -extensions available. On Solaris and IRIX if XFIXES -is not available, \fB-overlay\fR mode will be attempted. -.PP -\fB-cursor_drag\fR -.IP -Show cursor shape changes even when the mouse is being -dragged with a mouse button down. This is useful if you -want to be able to see Drag-and-Drop cursor icons, etc. -.PP -\fB-arrow\fR \fIn\fR -.IP -Choose an alternate "arrow" cursor from a set of -some common ones. n can be 1 to 6. Default is: 1 -Ignored when in XFIXES cursor-grabbing mode. -.PP -\fB-noxfixes\fR -.IP -Do not use the XFIXES extension to draw the exact cursor -shape even if it is available. -.IP -Note: To work around a crash in Xorg 1.5 and later -some people needed to use \fB-noxfixes.\fR The Xorg crash -occurred right after a Display Manager (e.g. GDM) login. -Starting with x11vnc 0.9.9 it tries to automatically -avoid using XFIXES until it is sure a window manager -is running. See the \fB-reopen\fR option for more info and -how to use X11VNC_AVOID_WINDOWS=never to disable it. -.PP -\fB-alphacut\fR \fIn\fR -.IP -When using the XFIXES extension for the cursor shape, -cursors with transparency will not usually be displayed -exactly (but opaque ones will). This option sets n as -a cutoff for cursors that have transparency ("alpha -channel" with values ranging from 0 to 255) Any cursor -pixel with alpha value less than n becomes completely -transparent. Otherwise the pixel is completely opaque. -Default 240 -.PP -\fB-alphafrac\fR \fIfraction\fR -.IP -With the threshold in \fB-alphacut\fR some cursors will become -almost completely transparent because their alpha values -are not high enough. For those cursors adjust the -alpha threshold until fraction of the non-zero alpha -channel pixels become opaque. Default 0.33 -.PP -\fB-alpharemove\fR -.IP -By default, XFIXES cursors pixels with transparency have -the alpha factor multiplied into the RGB color values -(i.e. that corresponding to blending the cursor with a -black background). Specify this option to remove the -alpha factor. (useful for light colored semi-transparent -cursors). -.PP -\fB-noalphablend\fR -.IP -In XFIXES mode do not send cursor alpha channel data -to LibVNCServer. The default is to send it. The -alphablend effect will only be visible in \fB-nocursorshape\fR -mode or for clients with cursorshapeupdates turned -off. (However there is a hack for 32bpp with depth 24, -it uses the extra 8 bits to store cursor transparency -for use with a hacked vncviewer that applies the -transparency locally. See the FAQ for more info). -.PP -\fB-nocursorshape\fR -.IP -Do not use the TightVNC CursorShapeUpdates extension -even if clients support it. See \fB-cursor\fR above. -.PP -\fB-cursorpos,\fR \fB-nocursorpos\fR -.IP -Option \fB-cursorpos\fR enables sending the X cursor position -back to all vnc clients that support the TightVNC -CursorPosUpdates extension. Other clients will be able -to see the pointer motions. Default: \fB-cursorpos\fR -.PP -\fB-xwarppointer,\fR \fB-noxwarppointer\fR -.IP -Move the pointer with -.IR XWarpPointer (3X) -instead of -the XTEST extension. Use this as a workaround -if the pointer motion behaves incorrectly, e.g. -on touchscreens or other non-standard setups. -.IP -It is also sometimes needed on XINERAMA displays and is -enabled by default if XINERAMA is found to be active. -To prevent this, use \fB-noxwarppointer.\fR -.PP -\fB-always_inject\fR -.IP -Even if there is no displacement (dx = dy = 0) for a -VNC mouse event force the pointer to the indicated x,y -position anyway. Recent (2009) gui toolkits (gnome) -have problems with x11vnc's original mouse input -injection method. So x11vnc's mouse input injection -method has been modified. To regain the OLD behavior -use this option: \fB-always_inject.\fR Then x11vnc will -always force positioning the mouse to the x,y position -even if that position has not changed since the previous -VNC input event. -.IP -The first place this problem was noticed was in gnome -terminal: if you pressed and released mouse button 3, a -menu was posted and then its first element 'New Terminal -Window' was activated. This was because x11vnc injected -the mouse position twice: once on ButtonPress and again -on ButtonRelease. The toolkit interpreted the 2nd one -as mouse motion even though the mouse hadn't moved. -So now by default x11vnc tries to avoid injecting the -2nd one. -.IP -Note that with the new default x11vnc will be oblivious -to applications moving the pointer (warping) or the -user at the physical display moving it. So it might, -e.g., inject ButtonRelease at the wrong position. -If this (or similar scenarios) causes problems in your -environment, specify \fB-always_inject\fR for the old method. -.PP -\fB-buttonmap\fR \fIstring\fR -.IP -String to remap mouse buttons. Format: IJK-LMN, this -maps buttons I -> L, etc., e.g. \fB-buttonmap\fR 13-31 -.IP -Button presses can also be mapped to keystrokes: replace -a button digit on the right of the dash with :<sym>: -or :<sym1>+<sym2>: etc. for multiple keys. For example, -if the viewing machine has a mouse-wheel (buttons 4 5) -but the x11vnc side does not, these will do scrolls: -.IP -\fB-buttonmap\fR 12345-123:Prior::Next: -.IP -\fB-buttonmap\fR 12345-123:Up+Up+Up::Down+Down+Down: -.IP -See <X11/keysymdef.h> header file for a list of Keysyms, -or use the -.IR xev (1) -program. Note: mapping of button -clicks to Keysyms may not work if \fB-modtweak\fR or \fB-xkb\fR is -needed for the Keysym. -.IP -If you include a modifier like "Shift_L" the -modifier's up/down state is toggled, e.g. to send -"The" use :Shift_L+t+Shift_L+h+e: (the 1st one is -shift down and the 2nd one is shift up). (note: the -initial state of the modifier is ignored and not reset) -To include button events use "Button1", ... etc. -.IP -.IP -\fB-buttonmap\fR currently does not work on MacOSX console -or in \fB-rawfb\fR mode. -.IP -Workaround: use \fB-buttonmap\fR IJ...-LM...=n to limit the -number of mouse buttons to n, e.g. 123-123=3. This will -prevent x11vnc from crashing if the X server reports -there are 5 buttons (4/5 scroll wheel), but there are -only really 3. -.PP -\fB-nodragging\fR -.IP -Do not update the display during mouse dragging events -(mouse button held down). Greatly improves response on -slow setups, but you lose all visual feedback for drags, -text selection, and some menu traversals. It overrides -any \fB-pointer_mode\fR setting. -.PP -\fB-ncache\fR \fIn\fR -.IP -Client-side caching scheme. Framebuffer memory \fIn\fR -(an integer) times that of the full display is allocated -below the actual framebuffer to cache screen contents -for rapid retrieval. So a W x H frambuffer is expanded -to a W x (n+1)*H one. Use 0 to disable. -.IP -The \fIn\fR is actually optional, the default is 10. -.IP -For this and the other \fB-ncache*\fR options below you can -abbreviate "\fB-ncache\fR" with "\fB-nc\fR". Also, "\fB-nonc\fR" -is the same as "\fB-ncache\fR \fI0\fR" -.IP -This is an experimental option, currently implemented in -an awkward way in that in the VNC Viewer you can see the -pixel cache contents if you scroll down, etc. So you -will have to set things up so you can't see that region. -If this method is successful, the changes required for -clients to do this less awkwardly will be investigated. -.IP -The SSVNC viewer does a good job at automatically hiding -the pixel cache region. Or use SSVNC's \fB-ycrop\fR option -to explicitly hide the region. -.IP -Note that this mode consumes a huge amount of memory, -both on the x11vnc server side and on the VNC Viewer -side. If n=2 then the amount of RAM used is roughly -tripled for both x11vnc and the VNC Viewer. As a rule -of thumb, note that 1280x1024 at depth 24 is about 5MB -of pixel data. -.IP -For reasonable response when cycling through 4 to 6 -large (e.g. web browser) windows a value n of 6 to 12 -is recommended. (that's right: ~10X more memory...) -.IP -Because of the way window backingstore and saveunders -are implemented, n must be even. It will be incremented -by 1 if it is not. -.IP -This mode also works for native MacOS X, but may not -be as effective as the X version. This is due to a -number of things, one is the drop-shadow compositing -that leaves extra areas that need to be repaired (see -\fB-ncache_pad).\fR Another is the window iconification -animations need to be avoided (see \fB-macicontime).\fR -It appears the that the 'Scale' animation mode gives -better results than the 'Genie' one. Also, window event -detection not as accurate as the X version. -.PP -\fB-ncache_cr\fR -.IP -In \fB-ncache\fR mode, try to do copyrect opaque window -moves/drags instead of wireframes (this can induce -painting errors). The wireframe will still be used when -moving a window whose save-unders has not yet been set -or has been invalidated. -.IP -Some VNC Viewers provide better response than others -with this option. On Unix, realvnc viewer gives -smoother drags than tightvnc viewer. Response may also -be choppy if the server side machine is too slow. -.IP -Sometimes on very slow modem connections, this actually -gives an improvement because no pixel data at all -(not even the box animation) is sent during the drag. -.PP -\fB-ncache_no_moveraise\fR -.IP -In \fB-ncache\fR mode, do not assume that moving a window -will cause the window manager to raise it to the top -of the stack. The default is to assume it does, and -so at the beginning of any wireframe, etc, window moves -the window will be pushed to top in the VNC viewer. -.PP -\fB-ncache_no_dtchange\fR -.IP -In \fB-ncache\fR mode, do not try to guess when the desktop -(viewport) changes to another one (i.e. another -workarea). The default is to try to guess and when -detected try to make the transistion more smoothly. -.PP -\fB-ncache_no_rootpixmap\fR -.IP -In \fB-ncache\fR mode, do not try to snapshot the desktop -background to use in guessing or reconstructing window -save-unders. -.PP -\fB-ncache_keep_anims\fR -.IP -In \fB-ncache\fR mode, do not try to disable window -manager animations and other effects (that usually -degrade ncache performance or cause painting errors). -The default is to try to disable them on KDE (but not -GNOME) when VNC clients are connected. -.IP -For other window managers or desktops that provide -animations, effects, compositing, translucency, -etc. that interfere with the \fB-ncache\fR method you will -have to disable them manually. -.PP -\fB-ncache_old_wm\fR -.IP -In \fB-ncache\fR mode, enable some heuristics for old style -window managers such as fvwm and twm. -.PP -\fB-ncache_pad\fR \fIn\fR -.IP -In \fB-ncache\fR mode, pad each window with n pixels for the -caching rectangles. This can be used to try to improve -the situation with dropshadows or other compositing -(e.g. MacOS X window manager), although it could make -things worse. The default is 0 on Unix and 24 on -MacOS X. -.PP -\fB-debug_ncache\fR -.IP -Turn on debugging and profiling output under \fB-ncache.\fR -.PP -\fB-wireframe\fR \fI[str],\fR \fB-nowireframe\fR -.IP -Try to detect window moves or resizes when a mouse -button is held down and show a wireframe instead of -the full opaque window. This is based completely on -heuristics and may not always work: it depends on your -window manager and even how you move things around. -See \fB-pointer_mode\fR below for discussion of the "bogging -down" problem this tries to avoid. -Default: \fB-wireframe\fR -.IP -Shorter aliases: \fB-wf\fR [str] and \fB-nowf\fR -.IP -The value "str" is optional and, of course, is -packed with many tunable parameters for this scheme: -.IP -Format: shade,linewidth,percent,T+B+L+R,mod,t1+t2+t3+t4 -Default: 0xff,2,0,32+8+8+8,all,0.15+0.30+5.0+0.125 -.IP -If you leave nothing between commas: ",," the default -value is used. If you don't specify enough commas, -the trailing parameters are set to their defaults. -.IP -"shade" indicate the "color" for the wireframe, -usually a greyscale: 0-255, however for 16 and 32bpp you -can specify an rgb.txt X color (e.g. "dodgerblue") or -a value > 255 is treated as RGB (e.g. red is 0xff0000). -"linewidth" sets the width of the wireframe in pixels. -"percent" indicates to not apply the wireframe scheme -to windows with area less than this percent of the -full screen. -.IP -"T+B+L+R" indicates four integers for how close in -pixels the pointer has to be from the Top, Bottom, Left, -or Right edges of the window to consider wireframing. -This is a speedup to quickly exclude a window from being -wireframed: set them all to zero to not try the speedup -(scrolling and selecting text will likely be slower). -.IP -"mod" specifies if a button down event in the -interior of the window with a modifier key (Alt, Shift, -etc.) down should indicate a wireframe opportunity. -It can be "0" or "none" to skip it, "1" or "all" -to apply it to any modifier, or "Shift", "Alt", -"Control", "Meta", "Super", or "Hyper" to only -apply for that type of modifier key. -.IP -"t1+t2+t3+t4" specify four floating point times in -seconds: t1 is how long to wait for the pointer to move, -t2 is how long to wait for the window to start moving -or being resized (for some window managers this can be -rather long), t3 is how long to keep a wireframe moving -before repainting the window. t4 is the minimum time -between sending wireframe "animations". If a slow -link is detected, these values may be automatically -changed to something better for a slow link. -.PP -\fB-nowireframelocal\fR -.IP -By default, mouse motion and button presses of a -user sitting at the LOCAL display are monitored for -wireframing opportunities (so that the changes will be -sent efficiently to the VNC clients). Use this option -to disable this behavior. -.PP -\fB-wirecopyrect\fR \fImode,\fR \fB-nowirecopyrect\fR -.IP -Since the \fB-wireframe\fR mechanism evidently tracks moving -windows accurately, a speedup can be obtained by -telling the VNC viewers to locally copy the translated -window region. This is the VNC CopyRect encoding: -the framebuffer update doesn't need to send the actual -new image data. -.IP -Shorter aliases: \fB-wcr\fR [mode] and \fB-nowcr\fR -.IP -"mode" can be "never" (same as \fB-nowirecopyrect)\fR -to never try the copyrect, "top" means only do it if -the window was not covered by any other windows, and -"always" means to translate the orginally unobscured -region (this may look odd as the remaining pieces come -in, but helps on a slow link). Default: "always" -.IP -Note: there can be painting errors or slow response -when using \fB-scale\fR so you may want to disable CopyRect -in this case "\fB-wirecopyrect\fR \fInever\fR" on the command -line or by remote-control. Or you can also use the -"\fB-scale\fR \fIxxx:nocr\fR" scale option. -.PP -\fB-debug_wireframe\fR -.IP -Turn on debugging info printout for the wireframe -heuristics. "\fB-dwf\fR" is an alias. Specify multiple -times for more output. -.PP -\fB-scrollcopyrect\fR \fImode,\fR \fB-noscrollcopyrect\fR -.IP -Like \fB-wirecopyrect,\fR but use heuristics to try to guess -if a window has scrolled its contents (either vertically -or horizontally). This requires the RECORD X extension -to "snoop" on X applications (currently for certain -XCopyArea and XConfigureWindow X protocol requests). -Examples: Hitting <Return> in a terminal window when the -cursor was at the bottom, the text scrolls up one line. -Hitting <Down> arrow in a web browser window, the web -page scrolls up a small amount. Or scrolling with a -scrollbar or mouse wheel. -.IP -Shorter aliases: \fB-scr\fR [mode] and \fB-noscr\fR -.IP -This scheme will not always detect scrolls, but when -it does there is a nice speedup from using the VNC -CopyRect encoding (see \fB-wirecopyrect).\fR The speedup -is both in reduced network traffic and reduced X -framebuffer polling/copying. On the other hand, it may -induce undesired transients (e.g. a terminal cursor -being scrolled up when it should not be) or other -painting errors (window tearing, bunching-up, etc). -These are automatically repaired in a short period -of time. If this is unacceptable disable the feature -with \fB-noscrollcopyrect.\fR -.IP -Screen clearing kludges: for testing at least, there -are some "magic key sequences" (must be done in less -than 1 second) to aid repairing painting errors that -may be seen when using this mode: -.IP -3 Alt_L's in a row: resend whole screen, -4 Alt_L's in a row: reread and resend whole screen, -3 Super_L's in a row: mark whole screen for polling, -4 Super_L's in a row: reset RECORD context, -5 Super_L's in a row: try to push a black screen -.IP -note: Alt_L is the Left "Alt" key (a single key) -Super_L is the Left "Super" key (Windows flag). -Both of these are modifier keys, and so should not -generate characters when pressed by themselves. Also, -your VNC viewer may have its own refresh hot-key -or button. -.IP -"mode" can be "never" (same as \fB-noscrollcopyrect)\fR -to never try the copyrect, "keys" means to try it -in response to keystrokes only, "mouse" means to -try it in response to mouse events only, "always" -means to do both. Default: "always" -.IP -Note: there can be painting errors or slow response -when using \fB-scale\fR so you may want to disable CopyRect -in this case "\fB-scrollcopyrect\fR \fInever\fR" on the command -line or by remote-control. Or you can also use the -"\fB-scale\fR \fIxxx:nocr\fR" scale option. -.PP -\fB-scr_area\fR \fIn\fR -.IP -Set the minimum area in pixels for a rectangle -to be considered for the \fB-scrollcopyrect\fR detection -scheme. This is to avoid wasting the effort on small -rectangles that would be quickly updated the normal way. -E.g. suppose an app updated the position of its skinny -scrollbar first and then shifted the large panel -it controlled. We want to be sure to skip the small -scrollbar and get the large panel. Default: 60000 -.PP -\fB-scr_skip\fR \fIlist\fR -.IP -Skip scroll detection for applications matching -the comma separated list of strings in \fIlist\fR. -Some applications implement their scrolling in -strange ways where the XCopyArea, etc, also applies -to invisible portions of the window: if we CopyRect -those areas it looks awful during the scroll and -there may be painting errors left after the scroll. -Soffice.bin is the worst known offender. -.IP -Use "##" to denote the start of the application class -(e.g. "##XTerm") and "++" to denote the start -of the application instance name (e.g. "++xterm"). -The string your list is matched against is of the form -"^^WM_NAME##Class++Instance<same-for-any-subwindows>" -The "xlsclients \fB-la"\fR command will provide this info. -.IP -If a pattern is prefixed with "KEY:" it only applies -to Keystroke generated scrolls (e.g. Up arrow). If it -is prefixed with "MOUSE:" it only applies to Mouse -induced scrolls (e.g. dragging on a scrollbar). -Default: ##Soffice.bin,##StarOffice,##OpenOffice -.PP -\fB-scr_inc\fR \fIlist\fR -.IP -Opposite of \fB-scr_skip:\fR this list is consulted first -and if there is a match the window will be monitored -via RECORD for scrolls irrespective of \fB-scr_skip.\fR -Use \fB-scr_skip\fR '*' to skip anything that does not match -your \fB-scr_inc.\fR Use \fB-scr_inc\fR '*' to include everything. -.PP -\fB-scr_keys\fR \fIlist\fR -.IP -For keystroke scroll detection, only apply the RECORD -heuristics to the comma separated list of keysyms in -\fIlist\fR. You may find the RECORD overhead for every -one of your keystrokes disrupts typing too much, but you -don't want to turn it off completely with "\fB-scr\fR \fImouse\fR" -and \fB-scr_parms\fR does not work or is too confusing. -.IP -The listed keysyms can be numeric or the keysym -names in the <X11/keysymdef.h> header file or from the -.IR xev (1) -program. Example: "\fB-scr_keys\fR \fIUp,Down,Return\fR". -One probably wants to have application specific lists -(e.g. for terminals, etc) but that is too icky to think -about for now... -.IP -If \fIlist\fR begins with the "-" character the list -is taken as an exclude list: all keysyms except those -list will be considered. The special string "builtin" -expands to an internal list of keysyms that are likely -to cause scrolls. BTW, by default modifier keys, -Shift_L, Control_R, etc, are skipped since they almost -never induce scrolling by themselves. -.PP -\fB-scr_term\fR \fIlist\fR -.IP -Yet another cosmetic kludge. Apply shell/terminal -heuristics to applications matching comma separated -list (same as for \fB-scr_skip/-scr_inc).\fR For example an -annoying transient under scroll detection is if you -hit Enter in a terminal shell with full text window, -the solid text cursor block will be scrolled up. -So for a short time there are two (or more) block -cursors on the screen. There are similar scenarios, -(e.g. an output line is duplicated). -.IP -These transients are induced by the approximation of -scroll detection (e.g. it detects the scroll, but not -the fact that the block cursor was cleared just before -the scroll). In nearly all cases these transient errors -are repaired when the true X framebuffer is consulted -by the normal polling. But they are distracting, so -what this option provides is extra "padding" near the -bottom of the terminal window: a few extra lines near -the bottom will not be scrolled, but rather updated -from the actual X framebuffer. This usually reduces -the annoying artifacts. Use "none" to disable. -Default: "term" -.PP -\fB-scr_keyrepeat\fR \fIlo-hi\fR -.IP -If a key is held down (or otherwise repeats rapidly) and -this induces a rapid sequence of scrolls (e.g. holding -down an Arrow key) the "scrollcopyrect" detection -and overhead may not be able to keep up. A time per -single scroll estimate is performed and if that estimate -predicts a sustainable scrollrate of keys per second -between "lo" and "hi" then repeated keys will be -DISCARDED to maintain the scrollrate. For example your -key autorepeat may be 25 keys/sec, but for a large -window or slow link only 8 scrolls per second can be -sustained, then roughly 2 out of every 3 repeated keys -will be discarded during this period. Default: "4-20" -.PP -\fB-scr_parms\fR \fIstring\fR -.IP -Set various parameters for the scrollcopyrect mode. -The format is similar to that for \fB-wireframe\fR and packed -with lots of parameters: -.IP -Format: T+B+L+R,t1+t2+t3,s1+s2+s3+s4+s5 -Default: 0+64+32+32,0.02+0.10+0.9,0.03+0.06+0.5+0.1+5.0 -.IP -If you leave nothing between commas: ",," the default -value is used. If you don't specify enough commas, -the trailing parameters are set to their defaults. -.IP -"T+B+L+R" indicates four integers for how close in -pixels the pointer has to be from the Top, Bottom, Left, -or Right edges of the window to consider scrollcopyrect. -If \fB-wireframe\fR overlaps it takes precedence. This is a -speedup to quickly exclude a window from being watched -for scrollcopyrect: set them all to zero to not try -the speedup (things like selecting text will likely -be slower). -.IP -"t1+t2+t3" specify three floating point times in -seconds that apply to scrollcopyrect detection with -*Keystroke* input: t1 is how long to wait after a key -is pressed for the first scroll, t2 is how long to keep -looking after a Keystroke scroll for more scrolls. -t3 is how frequently to try to update surrounding -scrollbars outside of the scrolling area (0.0 to -disable) -.IP -"s1+s2+s3+s4+s5" specify five floating point times -in seconds that apply to scrollcopyrect detection with -*Mouse* input: s1 is how long to wait after a mouse -button is pressed for the first scroll, s2 is how long -to keep waiting for additional scrolls after the first -Mouse scroll was detected. s3 is how frequently to -try to update surrounding scrollbars outside of the -scrolling area (0.0 to disable). s4 is how long to -buffer pointer motion (to try to get fewer, bigger -mouse scrolls). s5 is the maximum time to spend just -updating the scroll window without updating the rest -of the screen. -.PP -\fB-fixscreen\fR \fIstring\fR -.IP -Periodically "repair" the screen based on settings -in \fIstring\fR. Hopefully you won't need this option, -it is intended for cases when the \fB-scrollcopyrect\fR or -\fB-wirecopyrect\fR features leave too many painting errors, -but it can be used for any scenario. This option -periodically performs costly operations and so -interactive response may be reduced when it is on. -You can use 3 Alt_L's (the Left "Alt" key) taps in -a row (as described under \fB-scrollcopyrect)\fR instead to -manually request a screen repaint when it is needed. -.IP -\fIstring\fR is a comma separated list of one or more of -the following: "V=t", "C=t", "X=t", and "8=t". -In these "t" stands for a time in seconds (it is -a floating point even though one should usually use -values > 2 to avoid wasting resources). V sets how -frequently the entire screen should be sent to viewers -(it is like the 3 Alt_L's). C sets how long to wait -after a CopyRect to repaint the full screen. X sets -how frequently to reread the full X11 framebuffer from -the X server and push it out to connected viewers. -Use of X should be rare, please report a bug if you -find you need it. 8= applies only for \fB-8to24\fR mode: it -sets how often the non-default visual regions of the -screen (e.g. 8bpp windows) are refreshed. Examples: -\fB-fixscreen\fR V=10 \fB-fixscreen\fR C=10 -.PP -\fB-debug_scroll\fR -.IP -Turn on debugging info printout for the scroll -heuristics. "\fB-ds\fR" is an alias. Specify it multiple -times for more output. -.PP -\fB-noxrecord\fR -.IP -Disable any use of the RECORD extension. This is -currently used by the \fB-scrollcopyrect\fR scheme and to -monitor X server grabs. -.PP -\fB-grab_buster,\fR \fB-nograb_buster\fR -.IP -Some of the use of the RECORD extension can leave a -tiny window for XGrabServer deadlock. This is only if -the whole-server grabbing application expects mouse or -keyboard input before releasing the grab. It is usually -a window manager that does this. x11vnc takes care to -avoid the problem, but if caught x11vnc will freeze. -Without \fB-grab_buster,\fR the only solution is to go the -physical display and give it some input to satisfy the -grabbing app. Or manually kill and restart the window -manager if that is feasible. With \fB-grab_buster,\fR x11vnc -will fork a helper thread and if x11vnc appears to be -stuck in a grab after a period of time (20-30 sec) then -it will inject some user input: button clicks, Escape, -mouse motion, etc to try to break the grab. If you -experience a lot of grab deadlock, please report a bug. -.PP -\fB-debug_grabs\fR -.IP -Turn on debugging info printout with respect to -XGrabServer() deadlock for \fB-scrollcopyrect__mode_.\fR -.PP -\fB-debug_sel\fR -.IP -Turn on debugging info printout with respect to -PRIMARY, CLIPBOARD, and CUTBUFFER0 selections. -.PP -\fB-pointer_mode\fR \fIn\fR -.IP -Various pointer motion update schemes. "\fB-pm\fR" is -an alias. The problem is pointer motion can cause -rapid changes on the screen: consider the rapid -changes when you drag a large window around opaquely. -Neither x11vnc's screen polling and vnc compression -routines nor the bandwidth to the vncviewers can keep -up these rapid screen changes: everything will bog down -when dragging or scrolling. So a scheme has to be used -to "eat" much of that pointer input before re-polling -the screen and sending out framebuffer updates. The -mode number \fIn\fR can be 0 to 4 and selects one of -the schemes desribed below. -.IP -Note that the \fB-wireframe\fR and \fB-scrollcopyrect__mode_s\fR -complement \fB-pointer_mode\fR by detecting (and improving) -certain periods of "rapid screen change". -.IP -n=0: does the same as \fB-nodragging.\fR (all screen polling -is suspended if a mouse button is pressed.) -.IP -n=1: was the original scheme used to about Jan 2004: -it basically just skips \fB-input_skip\fR keyboard or pointer -events before repolling the screen. -.IP -n=2 is an improved scheme: by watching the current rate -of input events it tries to detect if it should try to -"eat" additional pointer events before continuing. -.IP -n=3 is basically a dynamic \fB-nodragging\fR mode: it detects -when the mouse motion has paused and then refreshes -the display. -.IP -n=4 attempts to measures network rates and latency, -the video card read rate, and how many tiles have been -changed on the screen. From this, it aggressively tries -to push screen "frames" when it decides it has enough -resources to do so. NOT FINISHED. -.IP -The default n is 2. Note that modes 2, 3, 4 will skip -\fB-input_skip\fR keyboard events (but it will not count -pointer events). Also note that these modes are not -available in \fB-threads\fR mode which has its own pointer -event handling mechanism. -.IP -To try out the different pointer modes to see which -one gives the best response for your usage, it is -convenient to use the remote control function, for -example "x11vnc \fB-R\fR pm:4" or the tcl/tk gui (Tuning -> -pointer_mode -> n). -.PP -\fB-input_skip\fR \fIn\fR -.IP -For the pointer handling when non-threaded: try to -read n user input events before scanning display. n < 0 -means to act as though there is always user input. -Default: 10 -.PP -\fB-allinput\fR -.IP -Have x11vnc read and process all available client input -before proceeding. -.PP -\fB-input_eagerly\fR -.IP -Similar to \fB-allinput\fR but use the handleEventsEagerly -mechanism built into LibVNCServer. -.PP -\fB-speeds\fR \fIrd,bw,lat\fR -.IP -x11vnc tries to estimate some speed parameters that -are used to optimize scheduling (e.g. \fB-pointer_mode\fR -4, \fB-wireframe,\fR \fB-scrollcopyrect)\fR and other things. -Use the \fB-speeds\fR option to set these manually. -The triple \fIrd,bw,lat\fR corresponds to video h/w -read rate in MB/sec, network bandwidth to clients in -KB/sec, and network latency to clients in milliseconds, -respectively. If a value is left blank, e.g. "-speeds -,100,15", then the internal scheme is used to estimate -the empty value(s). -.IP -Typical PC video cards have read rates of 5-10 MB/sec. -If the framebuffer is in main memory instead of video -h/w (e.g. SunRay, shadowfb, dummy driver, Xvfb), the -read rate may be much faster. "x11perf \fB-getimage500"\fR -can be used to get a lower bound (remember to factor -in the bytes per pixel). It is up to you to estimate -the network bandwith and latency to clients. For the -latency the -.IR ping (1) -command can be used. -.IP -For convenience there are some aliases provided, -e.g. "\fB-speeds\fR \fImodem\fR". The aliases are: "modem" for -6,4,200; "dsl" for 6,100,50; and "lan" for 6,5000,1 -.PP -\fB-wmdt\fR \fIstring\fR -.IP -For some features, e.g. \fB-wireframe\fR and \fB-scrollcopyrect,\fR -x11vnc has to work around issues for certain window -managers or desktops (currently kde and xfce). -By default it tries to guess which one, but it can -guess incorrectly. Use this option to indicate which -wm/dt. \fIstring\fR can be "gnome", "kde", "cde", -"xfce", or "root" (classic X wm). Anything else -is interpreted as "root". -.PP -\fB-debug_pointer\fR -.IP -Print debugging output for every pointer event. -.PP -\fB-debug_keyboard\fR -.IP -Print debugging output for every keyboard event. -.PP -Same as \fB-dp\fR and \fB-dk,\fR respectively. Use multiple -times for more output. -.PP -\fB-defer\fR \fItime\fR -.IP -Time in ms to delay sending updates to connected clients -(deferUpdateTime) Default: 20 -.PP -\fB-wait\fR \fItime\fR -.IP -Time in ms to pause between screen polls. Used to cut -down on load. Default: 20 -.PP -\fB-extra_fbur\fR \fIn\fR -.IP -Perform extra FrameBufferUpdateRequests checks to -try to be in better sync with the client's requests. -What this does is perform extra polls of the client -socket at critical times (before '-defer' and '-wait' -calls.) The default is n=1. Set to a larger number to -insert more checks or set to n=0 to disable. A downside -of these extra calls is that more mouse input may be -processed than desired. -.PP -\fB-wait_ui\fR \fIfactor\fR -.IP -Factor by which to cut the \fB-wait\fR time if there -has been recent user input (pointer or keyboard). -Improves response, but increases the load whenever you -are moving the mouse or typing. Default: 2.00 -.PP -\fB-setdefer\fR \fIn\fR -.IP -When the \fB-wait_ui\fR mechanism cuts down the wait time ms, -set the defer time to the same ms value. n=1 to enable, -0 to disable, and -1 to set defer to 0 (no delay). -Similarly, 2 and -2 indicate 'urgent_update' mode should -be used to push the updates even sooner. Default: 1 -.PP -\fB-nowait_bog\fR -.IP -Do not detect if the screen polling is "bogging down" -and sleep more. Some activities with no user input can -slow things down a lot: consider a large terminal window -with a long build running in it continuously streaming -text output. By default x11vnc will try to detect this -(3 screen polls in a row each longer than 0.25 sec with -no user input), and sleep up to 1.5 secs to let things -"catch up". Use this option to disable that detection. -.PP -\fB-slow_fb\fR \fItime\fR -.IP -Floating point time in seconds to delay all screen -polling. For special purpose usage where a low frame -rate is acceptable and desirable, but you want the -user input processed at the normal rate so you cannot -use \fB-wait.\fR -.PP -\fB-xrefresh\fR \fItime\fR -.IP -Floating point time in seconds to indicate how often to -do the equivalent of -.IR xrefresh (1) -to force all windows -(in the viewable area if \fB-id,\fR \fB-sid,\fR or \fB-clip\fR is used) -to repaint themselves. Use this only if applications -misbehave by not repainting themselves properly. -See also \fB-noxdamage.\fR -.PP -\fB-nap,\fR \fB-nonap\fR -.IP -Monitor activity and if it is low take longer naps -between screen polls to really cut down load when idle. -Default: take naps -.PP -\fB-sb\fR \fItime\fR -.IP -Time in seconds after NO activity (e.g. screen blank) -to really throttle down the screen polls (i.e. sleep -for about 1.5 secs). Use 0 to disable. Default: 60 -Set the env. var. X11VNC_SB_FACTOR to scale it. -.PP -\fB-readtimeout\fR \fIn\fR -.IP -Set LibVNCServer rfbMaxClientWait to n seconds. On -slow links that take a long time to paint the first -screen LibVNCServer may hit the timeout and drop the -connection. Default: 20 seconds. -.PP -\fB-ping\fR \fIn\fR -.IP -Send a 1x1 framebuffer update to all clients every n -seconds (e.g. to try to keep a network connection alive) -.PP -\fB-nofbpm,\fR \fB-fbpm\fR -.IP -If the system supports the FBPM (Frame Buffer Power -Management) extension (i.e. some Sun systems), then -prevent the video h/w from going into a reduced power -state when VNC clients are connected. -.IP -FBPM capable video h/w save energy when the workstation -is idle by going into low power states (similar to DPMS -for monitors). This interferes with x11vnc's polling -of the framebuffer data. -.IP -"\fB-nofbpm\fR" means prevent FBPM low power states whenever -VNC clients are connected, while "\fB-fbpm\fR" means to not -monitor the FBPM state at all. See the -.IR xset (1) -manpage -for details. \fB-nofbpm\fR is basically the same as running -"xset fbpm force on" periodically. Default: \fB-fbpm\fR -.PP -\fB-nodpms,\fR \fB-dpms\fR -.IP -If the system supports the DPMS (Display Power Management -Signaling) extension, then prevent the monitor from -going into a reduced power state when VNC clients -are connected. -.IP -DPMS reduced power monitor states are a good thing -and you normally want the power down to take place -(usually x11vnc has no problem exporting the display in -this state). You probably only want to use "\fB-nodpms\fR" -to work around problems with Screen Savers kicking -on in DPMS low power states. There is known problem -with kdesktop_lock on KDE where the screen saver keeps -kicking in every time user input stops for a second -or two. Specifying "\fB-nodpms\fR" works around it. -.IP -"\fB-nodpms\fR" means prevent DPMS low power states whenever -VNC clients are connected, while "\fB-dpms\fR" means to not -monitor the DPMS state at all. See the -.IR xset (1) -manpage -for details. \fB-nodpms\fR is basically the same as running -"xset dpms force on" periodically. Default: \fB-dpms\fR -.PP -\fB-forcedpms\fR -.IP -If the system supports the DPMS (Display Power -Management Signaling) extension, then try to keep the -monitor in a powered off state. This is to prevent -nosey people at the physical display from viewing what -is on the screen. Be sure to lock the screen before -disconnecting. -.IP -This method is far from bullet proof, e.g. suppose -someone attaches a non-DPMS monitor, or loads the -machine so that there is a gap of time before x11vnc -restores the powered off state? On many machines if -he floods it with keyboard and mouse input he can see -flashes of what is on the screen before the DPMS off -state is reestablished. For this to work securely -there would need to be support in the X server to do -this exactly rather than approximately with DPMS. -.PP -\fB-clientdpms\fR -.IP -As \fB-forcedpms\fR but only when VNC clients are connected. -.PP -\fB-noserverdpms\fR -.IP -The UltraVNC ServerInput extension is supported. -This allows the VNC viewer to click a button that will -cause the server (x11vnc) to try to disable keyboard -and mouse input at the physical display and put the -monitor in dpms powered off state. Use this option to -skip powering off the monitor. -.PP -\fB-noultraext\fR -.IP -Disable the following UltraVNC extensions: SingleWindow -and ServerInput. The others managed by LibVNCServer -(textchat, 1/n scaling, rfbEncodingUltra) are not. -.PP -\fB-chatwindow\fR -.IP -Place a local UltraVNC chat window on the X11 display -that x11vnc is polling. That way the person on the VNC -viewer-side can chat with the person at the physical -X11 console. (e.g. helpdesk w/o telephone) -.IP -For this to work the SSVNC package (version 1.0.21 or -later) MUST BE installed on the system where x11vnc runs -and the 'ssvnc' command must be available in $PATH. -The ssvncviewer is used as a chat window helper. -See http://www.karlrunge.com/x11vnc/ssvnc.html -.IP -This option implies '-rfbversion 3.6' so as to trick -UltraVNC viewers, otherwise they assume chat is not -available. To specify a different rfbversion, place -it after the \fB-chatwindow\fR option on the cmdline. -.IP -See also the remote control 'chaton' and 'chatoff' -actions. These can also be set from the tkx11vnc GUI. -.PP -\fB-noxdamage\fR -.IP -Do not use the X DAMAGE extension to detect framebuffer -changes even if it is available. Use \fB-xdamage\fR if your -default is to have it off. -.IP -x11vnc's use of the DAMAGE extension: 1) significantly -reduces the load when the screen is not changing much, -and 2) detects changed areas (small ones by default) -more quickly. -.IP -Currently the DAMAGE extension is overly conservative -and often reports large areas (e.g. a whole terminal -or browser window) as damaged even though the actual -changed region is much smaller (sometimes just a few -pixels). So heuristics were introduced to skip large -areas and use the damage rectangles only as "hints" -for the traditional scanline polling. The following -tuning parameters are introduced to adjust this -behavior: -.PP -\fB-xd_area\fR \fIA\fR -.IP -Set the largest DAMAGE rectangle area \fIA\fR (in -pixels: width * height) to trust as truly damaged: -the rectangle will be copied from the framebuffer -(slow) no matter what. Set to zero to trust *all* -rectangles. Default: 20000 -.PP -\fB-xd_mem\fR \fIf\fR -.IP -Set how long DAMAGE rectangles should be "remembered", -\fIf\fR is a floating point number and is in units of the -scanline repeat cycle time (32 iterations). The default -(1.0) should give no painting problems. Increase it if -there are problems or decrease it to live on the edge -(perhaps useful on a slow machine). -.PP -\fB-sigpipe\fR \fIstring\fR -.IP -Broken pipe (SIGPIPE) handling. \fIstring\fR can be -"ignore" or "exit". For "ignore" LibVNCServer -will handle the abrupt loss of a client and continue, -for "exit" x11vnc will cleanup and exit at the 1st -broken connection. -.IP -This option is not really needed since LibVNCServer -is doing the correct thing now for quite some time. -However, for convenience you can use it to ignore other -signals, e.g. "\fB-sigpipe\fR \fIignore:HUP,INT,TERM\fR" in case -that would be useful for some sort of application. -You can also put "exit:.." in the list to have x11vnc -cleanup on the listed signals. "\fB-sig\fR" is an alias -for this option if you don't like the 'pipe'. Example: -\fB-sig\fR ignore:INT,TERM,exit:USR1 -.PP -\fB-threads,\fR \fB-nothreads\fR -.IP -Whether or not to use the threaded LibVNCServer -algorithm [rfbRunEventLoop] if libpthread is available. -In this mode new threads (one for input and one -for output) are created to handle each new client. -Default: \fB-nothreads.\fR -.IP -Thread stability is much improved in version 0.9.8. -.IP -Multiple clients in threaded mode should be stable -for the ZRLE encoding on all platforms. The Tight and -Zlib encodings are currently only stable on Linux for -multiple clients. Compile with \fB-DTLS=__thread\fR if your -OS and compiler and linker support it. -.IP -For resizes (randr, etc.) set this env. var. to the number -of milliseconds to sleep: X11VNC_THREADS_NEW_FB_SLEEP -at various places in the do_new_fb() action. This is to -let various activities settle. Default is about 500ms. -.IP -Multiple clients in threaded mode could yield better -performance for 'class-room' broadcasting usage; also in -\fB-appshare\fR broadcast mode. See also the \fB-reflect\fR option. -.PP -\fB-fs\fR \fIf\fR -.IP -If the fraction of changed tiles in a poll is greater -than f, the whole screen is updated. Default: 0.75 -.PP -\fB-gaps\fR \fIn\fR -.IP -Heuristic to fill in gaps in rows or cols of n or -less tiles. Used to improve text paging. Default: 4 -.PP -\fB-grow\fR \fIn\fR -.IP -Heuristic to grow islands of changed tiles n or wider -by checking the tile near the boundary. Default: 3 -.PP -\fB-fuzz\fR \fIn\fR -.IP -Tolerance in pixels to mark a tiles edges as changed. -Default: 2 -.PP -\fB-debug_tiles\fR -.IP -Print debugging output for tiles, fb updates, etc. -.PP -\fB-snapfb\fR -.IP -Instead of polling the X display framebuffer (fb) -for changes, periodically copy all of X display fb -into main memory and examine that copy for changes. -(This setting also applies for non-X \fB-rawfb\fR modes). -Under some circumstances this will improve interactive -response, or at least make things look smoother, but in -others (most!) it will make the response worse. If the -video h/w fb is such that reading small tiles is very -slow this mode could help. To keep the "framerate" -up the screen size x bpp cannot be too large. Note that -this mode is very wasteful of memory I/O resources -(it makes full screen copies even if nothing changes). -It may be of use in video capture-like applications, -webcams, or where window tearing is a problem. -.PP -\fB-rawfb\fR \fIstring\fR -.IP -Instead of polling X, poll the memory object specified -in \fIstring\fR. -.IP -For file polling, to memory map -.IR mmap (2) -a file use: -"map:/path/to/a/file@WxHxB", with framebuffer Width, -Height, and Bits per pixel. "mmap:..." is the -same. -.IP -If there is trouble with mmap, use "file:/..." -for slower -.IR lseek (2) -based reading. -.IP -Use "snap:..." to imply \fB-snapfb\fR mode and the "file:" -access (this is for unseekable devices that only provide -the fb all at once, e.g. a video camera provides the -whole frame). -.IP -For shared memory segments string is of the form: -"shm:N@WxHxB" which specifies a shmid N and with -WxHxB as above. See -.IR shmat (1) -and -.IR ipcs (1) -.IP -If you do not supply a type "map" is assumed if -the file exists (see the next paragraphs for some -exceptions to this.) -.IP -If string is "setup:cmd", then the command "cmd" -is run and the first line from it is read and used -as \fIstring\fR. This allows initializing the device, -determining WxHxB, etc. These are often done as root -so take care. -.IP -If the string begins with "video", see the VIDEO4LINUX -discussion below where the device may be queried for -(and possibly set) the framebuffer parameters. -.IP -If the string begins with "console", "/dev/fb", -"fb", or "vt", see the LINUX CONSOLE discussion -below where the framebuffer device is opened and -keystrokes (and possibly mouse events) are inserted -into the console. -.IP -If the string begins with "vnc", see the VNC HOST -discussion below where the framebuffer is taken as that -of another remote VNC server. -.IP -Optional suffixes are ":R/G/B" and "+O" to specify -red, green, and blue masks (in hex) and an offset into -the memory object. If the masks are not provided x11vnc -guesses them based on the bpp (if the colors look wrong, -you need to provide the masks.) -.IP -Another optional suffix is the Bytes Per Line which in -some cases is not WxB/8. Specify it as WxHxB-BPL -e.g. 800x600x16-2048. This could be a normal width -1024 at 16bpp fb, but only width 800 shows up. -.IP -So the full format is: mode:file@WxHxB:R/G/B+O-BPL -.IP -Examples: -.IP -\fB-rawfb\fR shm:210337933@800x600x32:ff/ff00/ff0000 -.IP -\fB-rawfb\fR map:/dev/fb0@1024x768x32 -.IP -\fB-rawfb\fR map:/tmp/Xvfb_screen0@640x480x8+3232 -.IP -\fB-rawfb\fR file:/tmp/my.pnm@250x200x24+37 -.IP -\fB-rawfb\fR file:/dev/urandom@128x128x8 -\fB-rawfb\fR snap:/dev/video0@320x240x24 \fB-24to32\fR -\fB-rawfb\fR video0 -\fB-rawfb\fR video \fB-pipeinput\fR VID -\fB-rawfb\fR console -\fB-rawfb\fR vt2 -\fB-rawfb\fR vnc:somehost:0 -.IP -(see -.IR ipcs (1) -and -.IR fbset (1) -for the first two examples) -.IP -In general all user input is discarded by default (see -the \fB-pipeinput\fR option for how to use a helper program -to insert). Most of the X11 (screen, keyboard, mouse) -options do not make sense and many will cause this -mode to crash, so please think twice before setting or -changing them in a running x11vnc. -.IP -If you DO NOT want x11vnc to close the X DISPLAY in -rawfb mode, prepend a "+" e.g. +file:/dev/fb0... -Keeping the display open enables the default -remote-control channel, which could be useful. -Alternatively, if you specify \fB-noviewonly,\fR then the -mouse and keyboard input are STILL sent to the X -display, this usage should be very rare, i.e. doing -something strange with /dev/fb0. -.IP -If the device is not "seekable" (e.g. webcam) try -reading it all at once in full snaps via the "snap:" -mode (note: this is a resource hog). If you are using -file: or map: AND the device needs to be reopened for -*every* snapfb snapshot, set the environment variable: -SNAPFB_RAWFB_RESET=1 as well. -.IP -If you want x11vnc to dynamically transform a 24bpp -rawfb to 32bpp (note that this will be slower) also -supply the \fB-24to32\fR option. This would be useful for, -say, a video camera that delivers the pixel data as -24bpp packed RGB. This is the default under "video" -mode if the bpp is 24. -.IP -Normally the bits per pixel, B, is 8, 16, or 32 (or -rarely 24), however there is also some support for -B < 8 (e.g. old graphics displays 4 bpp or 1 bpp). -In this case you certainly must supply the masks as -well: WxHxB:R/G/B. The pixels will be padded out to -8 bpp using depth 8 truecolor. The scheme currently -does not work with snap fb (ask if interested.) B=1 -monochrome example: file:/dev/urandom@128x128x1:1/1/1 -Some other like this are 128x128x2:3/3/3 128x128x4:7/7/7 -.IP -For B < 8 framebuffers you can also set the env. var -RAWFB_CGA=1 to try a CGA mapping for B=4 (e.g. linux -vga16fb driver.) Note with low bpp and/or resolution -VGA and VGA16 modes on the Linux console one's attempt -to export them via x11vnc can often be thwarted due to -special color palettes, pixel packings, and even video -painting buffering. OTOH, often experimenting with the -RGB masks can yield something recognizable. -.IP -VIDEO4LINUX: on Linux some attempt is made to handle -video devices (webcams or TV tuners) automatically. -The idea is the WxHxB will be extracted from the -device itself. So if you do not supply "@WxHxB... -parameters x11vnc will try to determine them. It first -tries the v4l API if that support has been compiled in. -Otherwise it will run the v4l- -.IR info (1) -external program -if it is available. -.IP -The simplest examples are "\fB-rawfb\fR \fIvideo\fR" and "-rawfb -video1" which imply the device file /dev/video and -/dev/video1, respectively. You can also supply the -/dev if you like, e.g. "\fB-rawfb\fR \fI/dev/video0\fR" -.IP -Since the video capture device framebuffer usually -changes continuously (e.g. brightness fluctuations), -you may want to use the \fB-wait,\fR \fB-slow_fb,\fR or \fB-defer\fR -options to lower the "framerate" to cut down on -network VNC traffic. -.IP -A more sophisticated video device scheme allows -initializing the device's settings using: -.IP -\fB-rawfb\fR video:<settings> -.IP -The prefix could also be, as above, e.g. "video1:" to -specify the device file. The v4l API must be available -for this to work. Otherwise, you will need to try -to initialize the device with an external program, -e.g. xawtv, spcaview, and hope they persist when x11vnc -re-opens the device. -.IP -<settings> is a comma separated list of key=value pairs. -The device's brightness, color, contrast, and hue can -be set to percentages, e.g. br=80,co=50,cn=44,hu=60. -.IP -The device filename can be set too if needed (if it -does not start with "video"), e.g. fn=/dev/qcam. -.IP -The width, height and bpp of the framebuffer can be -set via, e.g., w=160,h=120,bpp=16. -.IP -Related to the bpp above, the pixel format can be set -via the fmt=XXX, where XXX can be one of: GREY, HI240, -RGB555, RGB565, RGB24, and RGB32 (with bpp 8, 8, 16, 16, -24, and 32 respectively). See http://www.linuxtv.org -for more info (V4L api). -.IP -For TV/rf tuner cards one can set the tuning mode -via tun=XXX where XXX can be one of PAL, NTSC, SECAM, -or AUTO. -.IP -One can switch the input channel by the inp=XXX setting, -where XXX is the name of the input channel (Television, -Composite1, S-Video, etc). Use the name that is in the -information about the device that is printed at startup. -.IP -For input channels with tuners (e.g. Television) one -can change which station is selected by the sta=XXX -setting. XXX is the station number. Currently only -the ntsc-cable-us (US cable) channels are built into -x11vnc. See the \fB-freqtab\fR option below to supply one -from xawtv. If XXX is greater than 500, then it is -interpreted as a raw frequency in KHz. -.IP -Example: -.IP -\fB-rawfb\fR video:br=80,w=320,h=240,fmt=RGB32,tun=NTSC,sta=47 -.IP -one might need to add inp=Television too for the input -channel to be TV if the card doesn't come up by default -in that one. -.IP -Note that not all video capture devices will support -all of the above settings. -.IP -See the \fB-pipeinput\fR VID option below for a way to control -the settings through the VNC Viewer via keystrokes. -As a shortcut, if the string begins "Video.." instead -of "video.." then \fB-pipeinput\fR VID is implied. -.IP -As above, if you specify a "@WxHxB..." after the -<settings> string they are used verbatim: the device -is not queried for the current values. Otherwise the -device will be queried. -.IP -LINUX CONSOLE: The following describes some ways to -view and possibly interact with the Linux text/graphics -console (i.e. not X11 XFree86/Xorg) -.IP -Note: If the LibVNCServer LinuxVNC program is on your -system you may want to use that instead of the following -method because it will be faster and more accurate -for the Linux text console and includes mouse support. -There is, however, the basic LinuxVNC functionality in -x11vnc if you replace "console" with "vt" in the -examples below. -.IP -If the rawfb string begins with "console" the -framebuffer device /dev/fb0 is opened and /dev/tty0 is -opened too. The latter is used to inject keystrokes -(not all are supported, but the basic ones are). -You will need to be root to inject keystrokes, but -not necessarily to open /dev/fb0. /dev/tty0 refers to -the active VT, to indicate one explicitly, use, e.g., -"console2" for /dev/tty2, etc. by indicating the -specific VT number. -.IP -For the Linux framebuffer device, /dev/fb0, (fb1, -etc) to be enabled the appropriate kernel drivers must -be loaded. E.g. vesafb or vga16fb and also by setting -the boot parameter vga=0x301 (or 0x314, 0x317, etc.) -(The vga=... method is the preferred way; set your -machines up that way.) Otherwise there will be a -\'No such device' error. You can also load a Linux -framebuffer driver specific to your make of video card -for more functionality. Once the machine is booted one -can often 'modprobe' the fb driver as root to obtain -a framebuffer device. -.IP -If you cannot get /dev/fb0 working on Linux, try -using the LinuxVNC emulation mode by "\fB-rawfb\fR \fIvtN\fR" -where N = 1, ... 6 is the Linux Virtual Terminal (aka -virtual console) you wish to view, e.g. "\fB-rawfb\fR \fIvt2\fR". -Unlike /dev/fb mode, it need not be the active Virtual -Terminal. Note that this mode can only show text and -not graphics. x11vnc polls the text in /dev/vcsaN -.IP -Set the env. var. RAWFB_VCSA_BW=1 to disable colors in -the "vtN" mode (i.e. black and white only.) If you -do not prefer the default 16bpp set RAWFB_VCSA_BPP to -8 or 32. If you need to tweak the rawfb parameters by -using the 'console_guess' string printed at startup, -be sure to indicate the snap: method. -.IP -uinput: If the Linux version appears to be 2.6 -or later and the "uinput" module appears to be -present (modprobe uinput), then the uinput method -will be used instead of /dev/ttyN. uinput allows -insertion of BOTH keystrokes and mouse input and so it -preferred when accessing graphical (e.g. QT-embedded) -linux console apps. It also provides more accurate -keystroke insertion. See \fB-pipeinput\fR UINPUT below for -more information on this mode; you will have to use -\fB-pipeinput\fR if you want to tweak any UINPUT parameters. -You may also want to also use the \fB-nodragging\fR and -\fB-cursor\fR none options. Use "console0", etc or -\fB-pipeinput\fR CONSOLE to force the /dev/ttyN method. -.IP -Note you can change the Linux VT remotely using the -.IR chvt (1) -command to make the one you want be the active -one (e.g. 'chvt 3'). Sometimes switching out and back -corrects the framebuffer's graphics state. For the -"\fB-rawfb\fR \fIvtN\fR" mode there is no need to switch the VT's. -.IP -To skip input injecting entirely use "consolex" -or "vtx". -.IP -The string "/dev/fb0" (1, etc.) can be used instead -of "console". This can be used to specify a different -framebuffer device, e.g. /dev/fb1. As a shortcut the -"/dev/" can be dropped. If the name is something -nonstandard, use "console:/dev/foofb" -.IP -If you do not want x11vnc to guess the framebuffer's -WxHxB and masks automatically (sometimes the kernel -gives incorrect information), specify them with a @WxHxB -(and optional :R/G/B masks) at the end of the string. -.IP -Examples: -\fB-rawfb\fR console -\fB-rawfb\fR /dev/fb0 (same) -\fB-rawfb\fR console3 (force /dev/tty3) -\fB-rawfb\fR consolex (no keystrokes or mouse) -\fB-rawfb\fR console:/dev/nonstd -\fB-rawfb\fR console \fB-pipeinput\fR UINPUT:accel=4.0 -\fB-rawfb\fR vt3 (/dev/tty3 w/o /dev/fb0) -.IP -VNC HOST: if the \fB-rawfb\fR string is of the form -"vnc:host:N" then the VNC display "N" on the remote -VNC server "host" is connected to (i.e. x11vnc acts as -a VNC client itself) and that framebuffer is exported. -.IP -This mode is really only of use if you are trying -to improve performance in the case of many (e.g. > -10) simultaneous VNC viewers, and you try a divide -and conquer scheme to reduce bandwidth and improve -responsiveness. (However, another user found this mode -useful to export a demo display through a slow link: -then multiple demo viewers connected to the reflecting -x11vnc on the fast side of the link, and so avoided -all of the demo viewers going through the slow link.) -.IP -For example, if there will be 64 simultaneous VNC -viewers this can lead to a lot of redundant VNC traffic -to and from the server host:N, extra CPU usage, -and all viewers response can be reduced by having -to wait for writes to the slowest client to finish. -However, if you set up 8 reflectors/repeaters started -with option \fB-rawfb\fR vnc:host:N, then there are only -8 connections to host:N. Each repeater then handles -8 vnc viewer connections thereby spreading the load -around. In classroom broadcast usage, try to put the -repeaters on different switches. This mode is the same -as \fB-reflect\fR host:N. Replace "host:N" by "listen" -or "listen:port" for a reverse connection. -.IP -Overall performance will not be as good as a single -direct connection because, among other things, -there is an additional level of framebuffer polling -and pointer motion can still induce many changes per -second that must be propagated. Tip: if the remote VNC -is x11vnc doing wireframing, or an X display that does -wireframing that gives much better response than opaque -window dragging. Consider the \fB-nodragging\fR option if -the problem is severe. -.IP -The env. var. X11VNC_REFLECT_PASSWORD can be set to -the password needed to log into the vnc host server, or -to "file:path_to_file" to indicate a file containing -the password as its first line. -.IP -To set the pixel format that x11vnc requests as a VNC -CLIENT set the env. vars: X11VNC_REFLECT_bitsPerSample -X11VNC_REFLECT_samplesPerPixel, and -X11VNC_REFLECT_bytesPerPixel; the defaults are 8, 3, 4. -2, 3, 1 would give a low color mode. See the function -rfbGetClient() in libvncclient for more info. -.IP -The VNC HOST mode implies \fB-shared.\fR Use \fB-noshared\fR as -a subsequent cmdline option to disable sharing. -.PP -\fB-freqtab\fR \fIfile\fR -.IP -For use with "\fB-rawfb\fR \fIvideo\fR" for TV tuner devices to -specify station frequencies. Instead of using the built -in ntsc-cable-us mapping of station number to frequency, -use the data in file. For stations that are not -numeric, e.g. SE20, they are placed above the highest -numbered station in the order they are found. Example: -"\fB-freqtab\fR \fI/usr/X11R6/share/xawtv/europe-west.list\fR" -You can make your own freqtab by copying the xawtv -format. -.PP -\fB-pipeinput\fR \fIcmd\fR -.IP -This option lets you supply an external command in -\fIcmd\fR that x11vnc will pipe all of the user input -events to in a simple format. In \fB-pipeinput\fR mode by -default x11vnc will not process any of the user input -events. If you prefix \fIcmd\fR with "tee:" it will -both send them to the pipe command and process them. -For a description of the format run "-pipeinput -tee:/bin/cat". Another prefix is "reopen" which -means to reopen pipe if it exits. Separate multiple -prefixes with commas. -.IP -In combination with \fB-rawfb\fR one might be able to -do amusing things (e.g. control non-X devices). -To facilitate this, if \fB-rawfb\fR is in effect then the -value is stored in X11VNC_RAWFB_STR for the pipe command -to use if it wants. Do 'env | grep X11VNC' for more. -.IP -Built-in pipeinput modes (no external program required): -.IP -If cmd is "VID" and you are using the \fB-rawfb\fR for a -video capture device, then an internal list of keyboard -mappings is used to set parameters of the video. -The mappings are: -.IP -"B" and "b" adjust the brightness up and down. -"H" and "h" adjust the hue. -"C" and "c" adjust the colour. -"N" and "n" adjust the contrast. -"S" and "s" adjust the size of the capture screen. -"I" and "i" cycle through input channels. -Up and Down arrows adjust the station (if a tuner) -F1, F2, ..., F6 will switch the video capture pixel -format to HI240, RGB565, RGB24, RGB32, RGB555, and -GREY respectively. See \fB-rawfb\fR video for details. -.IP -If cmd is "CONSOLE" or "CONSOLEn" where n -is a Linux console number, then the linux console -keystroke insertion to /dev/ttyN (see \fB-rawfb\fR console) -is performed. -.IP -If cmd begins with "UINPUT" then the Linux uinput -module is used to insert both keystroke and mouse events -to the Linux console (see \fB-rawfb\fR above). This usually -is the /dev/input/uinput device file (you may need to -create it with "mknod /dev/input/uinput c 10 223" -and insert the module with "modprobe uinput". -.IP -The UINPUT mode currently only does US keyboards (a -scan code option may be added), and not all keysyms -are supported. But it is probably more accurate than -the "CONSOLE" method. -.IP -You may want to use the options \fB-cursor\fR none and -\fB-nodragging\fR in this mode. -.IP -Additional tuning options may be supplied via: -UINPUT:opt1,opt2,... (a comma separated list). If an -option begins with "/" it is taken as the uinput -device file. -.IP -Which uinput is injected can be controlled by an option -string made of the characters "K", "M", and "B" -(see the \fB-input\fR option), e.g. "KM" allows keystroke -and motion but not button clicks. -.IP -A UINPUT option of the form: accel=f, or accel=fx+fy -sets the mouse motion "acceleration". This is used -to correct raw mouse relative motion into how much the -application cursor moves (x11vnc has no control over, -or knowledge of how the windowing application interprets -the raw mouse motions). Typically the acceleration -for an X display is 2 (see xset "m" option). "f" -is a floating point number, e.g. 3.0. Use "fx+fy" -if you need to supply different corrections for x and y. -.IP -Note: the default acceleration is 2.0 since it seems -both X and qt-embedded often (but not always) use -this value. -.IP -Even with a correct accel setting the mouse position -will get out of sync (probably due to a mouse -"threshold" setting where the acceleration doe not -apply, set -.IR xset (1) -). The option reset=N sets the -number of ms (default 150) after which the cursor is -attempted to be reset (by forcing the mouse to (0, -0) via small increments and then back out to (x, y) -in 1 jump), This correction seems to be needed but can -cause jerkiness or unexpected behavior with menus, etc. -Use reset=0 to disable. -.IP -If you set the env. var X11VNC_UINPUT_THRESHOLDS then -the thresh=n mode will be enabled. It is currently -not working well. If |dx| <= thresh and |dy| < thresh -no acceleration is applied. Use "thresh=+n" |dx| + -|dy| < thresh to be used instead (X11?) -.IP -Example: -\fB-pipeinput\fR UINPUT:accel=4.0 \fB-cursor\fR none -.IP -If the uinput device has an absolute pointer (as opposed -to a normal mouse that is a relative pointer) you can -specify the option "abs". Note that a touchpad -on a laptop is an absolute device to some degree. -This (usually) avoids all the problems with mouse -acceleration. If x11vnc has trouble deducing the -size of the device, use "abs=WxH". Furthermore, -if the device is a touchscreen (assumed to have an -absolute pointer) use "touch" or "touch=WxH". -For touchscreens, when a mouse button is pressed, -a pressure increase is injected, and when the button -is released a pressure of zero is injected. -.IP -If touch has been set, use "touch_always=1" to -indicate whenever the mouse moves with no button -pressed, a touch event of zero pressure should be -sent anyway. Also use "btn_touch=1" to indicate a -BTN_TOUCH keystroke press or release should be sent -instead of a pressure change. Set "dragskip=n" to -skip n dragged mouse touches (with pressure applied) -before injecting one. To indicate the pressure that -should be sent when there is a button click for a -touchscreen device, specify pressure=n, e.g. n=5. The -default is n=1. -.IP -If a touch screen is being used ("touch" above) -and it is having its input processed by tslib, you can -specify the tslib calibration file via tslib_cal=<file>. -For example, tslib_cal=/etc/pointercal. To get accurate -or even usable positioning this is required when tslib -is in use. -.IP -The Linux uinput mechanism can be bypassed and one can -write input events DIRECTLY to the devices instead. -To do this, specify one or more of the following -for the input classes: direct_rel=<device> -direct_abs=<device> direct_btn=<device> or -direct_key=<device>. The <device> file is usually -something like /dev/input/event1 but you can specify -any device file or pipe. You must specify each one -of the above classes even if they correspond to the -same device file (rel/abs and btn are often the same.) -Look at the file /proc/bus/input/devices to get an idea -what is available and the device filenames. Note: -The /dev/input/mouse* devices do not seem to work, -use the corresponding /dev/input/event* file instead. -Any input class not directly specified as above will be -handled via the uinput mechanism. To disable creating a -uinput device (and thereby discarding unhandled input), -specify "nouinput". -.IP -Examples: -.IP -\fB-pipeinput\fR UINPUT:direct_abs=/dev/input/event1 -.IP -this was used on a qtmoko Neo freerunner (armel): -.IP -\fB-pipeinput\fR UINPUT:touch,tslib_cal=/etc/pointercal, -direct_abs=/dev/input/event1,nouinput,dragskip=4 -.IP -(where the long line has been split into two.) -.IP -You can set the env. var X11VNC_UINPUT_DEBUG=1 or higher -to get debugging output for UINPUT mode. -.PP -\fB-macnodim\fR -.IP -For the native MacOSX server, disable dimming. -.PP -\fB-macnosleep\fR -.IP -For the native MacOSX server, disable display sleep. -.PP -\fB-macnosaver\fR -.IP -For the native MacOSX server, disable screensaver. -.PP -\fB-macnowait\fR -.IP -For the native MacOSX server, do not wait for the -user to switch back to his display. -.PP -\fB-macwheel\fR \fIn\fR -.IP -For the native MacOSX server, set the mouse wheel -speed to n (default 5). -.PP -\fB-macnoswap\fR -.IP -For the native MacOSX server, do not swap mouse -buttons 2 and 3. -.PP -\fB-macnoresize\fR -.IP -For the native MacOSX server, do not resize or reset -the framebuffer even if it is detected that the screen -resolution or depth has changed. -.PP -\fB-maciconanim\fR \fIn\fR -.IP -For the native MacOSX server, set n to the number -of milliseconds that the window iconify/deiconify -animation takes. In \fB-ncache\fR mode this value will be -used to skip the animation if possible. (default 400) -.PP -\fB-macmenu\fR -.IP -For the native MacOSX server, in \fB-ncache\fR client-side -caching mode, try to cache pull down menus (not perfect -because they have animated fades, etc.) -.PP -\fB-macuskbd\fR -.IP -For the native MacOSX server, use the original -keystroke insertion code based on a US keyboard. -.PP -\fB-macnoopengl\fR -.IP -For the native MacOSX server, do not use OpenGL for -screen capture, but rather use the original, deprecated -raw memory access method: addr = CGDisplayBaseAddress(). -.PP -\fB-macnorawfb\fR -.IP -For the native MacOSX server, disable the raw memory -address screen capture method. -.IP -MACOSX NOTE: There are some deprecated MacOSX interfaces -to inject keyboard and mouse events and the raw memory -access method is deprecated as well (however, OpenGL -will be preferred if available because it is faster.) -One can force not using any deprecated interfaces at -compile time by setting \fB-DX11VNC_MACOSX_NO_DEPRECATED=1\fR -in CPPFLAGS. Or to turn them off one by one: -\fB-DX11VNC_MACOSX_NO_DEPRECATED_LOCALEVENTS=1,\fR -\fB-DX11VNC_MACOSX_NO_DEPRECATED_POSTEVENTS=1\fR or -\fB-DX11VNC_MACOSX_NO_DEPRECATED_FRAMEBUFFER=1\fR -At run time, for testing and workarounds, one can -disable them by using: -\fB-env\fR X11VNC_MACOSX_NO_DEPRECATED=1 -\fB-env\fR X11VNC_MACOSX_NO_DEPRECATED_LOCALEVENTS=1 -\fB-env\fR X11VNC_MACOSX_NO_DEPRECATED_POSTEVENTS=1 or -\fB-env\fR X11VNC_MACOSX_NO_DEPRECATED_FRAMEBUFFER=1 -Note: When doing either of these for the mouse input -not everything works currently, e.g. double clicks and -wireframing. Also, screen resolution and pixel depth -changes will not be automatically detected unless the -deprecated framebuffer interfaces are allowed. -.IP -Conversely, if you are compiling on an -older machine that does not have some of -the newer interfaces, you may need to specify -\fB-DX11VNC_MACOSX_NO_CGEVENTCREATESCROLLWHEELEVENT\fR -\fB-DX11VNC_MACOSX_NO_CGEVENTCREATEMOUSEEVENT\fR or -\fB-DX11VNC_MACOSX_NO_CGEVENTCREATEKEYBOARDEVENT.\fR Use -\fB-DX11VNC_MACOSX_USE_GETMAINDEVICE\fR to regain the very -old QuickDraw GetMainDevice() interface (rare...) -.PP -\fB-gui\fR \fI[gui-opts]\fR -.IP -Start up a simple tcl/tk gui based on the remote -control options \fB-remote/-query\fR described below. -Requires the "wish" program to be installed on the -machine. "gui-opts" is not required: the default -is to start up both the full gui and x11vnc with the -gui showing up on the X display in the environment -variable DISPLAY. -.IP -"gui-opts" can be a comma separated list of items. -Currently there are these types of items: 1) a gui -mode, a 2) gui "simplicity", 3) the X display the -gui should display on, 4) a "tray" or "icon" mode, -and 5) a gui geometry. -.IP -1) The gui mode can be "start", "conn", or "wait" -"start" is the default mode above and is not required. -"conn" means do not automatically start up x11vnc, -but instead just try to connect to an existing x11vnc -process. "wait" means just start the gui and nothing -else (you will later instruct the gui to start x11vnc -or connect to an existing one.) -.IP -2) The gui simplicity is off by default (a power-user -gui with all options is presented) To start with -something less daunting supply the string "simple" -("ez" is an alias for this). Once the gui is -started you can toggle between the two with "Misc -> -simple_gui". -.IP -3) Note the possible confusion regarding the potentially -two different X displays: x11vnc polls one, but you -may want the gui to appear on another. For example, if -you ssh in and x11vnc is not running yet you may want -the gui to come back to you via your ssh redirected X -display (e.g. localhost:10). -.IP -If you do not specify a gui X display in "gui-opts" -then the DISPLAY environment variable and \fB-display\fR -option are tried (in that order). Regarding the x11vnc -X display the gui will try to communication with, it -first tries \fB-display\fR and then DISPLAY. For example, -"x11vnc \fB-display\fR :0 \fB-gui\fR otherhost:0", will remote -control an x11vnc polling :0 and display the gui on -otherhost:0 The "tray/icon" mode below reverses this -preference, preferring to display on the x11vnc display. -.IP -4) When "tray" or "icon" is specified, the gui -presents itself as a small icon with behavior typical -of a "system tray" or "dock applet". The color -of the icon indicates status (connected clients) and -there is also a balloon status. Clicking on the icon -gives a menu from which properties, etc, can be set and -the full gui is available under "Advanced". To be -fully functional, the gui mode should be "start" -(the default). -.IP -Note that tray or icon mode will imply the \fB-forever\fR -x11vnc option (if the x11vnc server is started along -with the gui) unless \fB-connect\fR or \fB-connect_or_exit\fR has -been specified. So x11vnc (and the tray/icon gui) -will wait for more connections after the first client -disconnects. If you want only one viewer connection -include the \fB-once\fR option. -.IP -For "icon" the gui just a small standalone window. -For "tray" it will attempt to embed itself in the -"system tray" if possible. If "=setpass" is appended then -at startup the X11 user will be prompted to set the -VNC session password. If =<hexnumber> is appended -that icon will attempt to embed itself in the window -given by hexnumber. Use =noadvanced to disable the -full gui. (To supply more than one, use "+" sign). -E.g. \fB-gui\fR tray=setpass and \fB-gui\fR icon=0x3600028 -.IP -Other modes: "full", the default and need not be -specified. "\fB-gui\fR \fInone\fR", do not show a gui, useful -to override a ~/.x11vncrc setting, etc. -.IP -5) When "geom=+X+Y" is specified, that geometry -is passed to the gui toplevel. This is the icon in -icon/tray mode, or the full gui otherwise. You can -also specify width and height, i.e. WxH+X+Y, but it -is not recommended. In "tray" mode the geometry is -ignored unless the system tray manager does not seem -to be running. One could imagine using something like -"\fB-gui\fR \fItray,geom=+4000+4000\fR" with a display manager -to keep the gui invisible until someone logs in... -.IP -More icon tricks, "icon=minimal" gives an icon just -with the VNC display number. You can also set the font -with "iconfont=...". The following could be useful: -"\fB-gui\fR \fIicon=minimal,iconfont=5x8,geom=24x10+0-0\fR" -.IP -General examples of the \fB-gui\fR option: "x11vnc \fB-gui",\fR -"x11vnc \fB-gui\fR ez" "x11vnc \fB-gui\fR localhost:10", -"x11vnc \fB-gui\fR conn,host:0", "x11vnc \fB-gui\fR tray,ez" -"x11vnc \fB-gui\fR tray=setpass" -.IP -If you do not intend to start x11vnc from the gui -(i.e. just remote control an existing one), then the -gui process can run on a different machine from the -x11vnc server as long as X permissions, etc. permit -communication between the two. -.IP -FONTS: On some systems the tk fonts can be too small, -jagged, or otherwise unreadable. There are 4 env vars -you can set to be the tk font you prefer: -.IP -X11VNC_FONT_BOLD main font for menus and buttons. -X11VNC_FONT_FIXED font for fixed width text. -.IP -X11VNC_FONT_BOLD_SMALL tray icon font. -X11VNC_FONT_REG_SMALL tray icon menu font. -.IP -The last two only apply for the tray icon mode. -.IP -Here are some examples: -.IP -\fB-env\fR X11VNC_FONT_BOLD='Helvetica \fB-16\fR bold' -\fB-env\fR X11VNC_FONT_FIXED='Courier \fB-14'\fR -\fB-env\fR X11VNC_FONT_REG_SMALL='Helvetica \fB-12'\fR -.IP -You can put the lines like the above (without the -quotes) in your ~/.x11vncrc file to avoid having to -specify them on the x11vnc command line. -.PP -\fB-remote\fR \fIcommand\fR -.IP -Remotely control some aspects of an already running -x11vnc server. "\fB-R\fR" and "\fB-r\fR" are aliases for -"\fB-remote\fR". After the remote control command is -sent to the running server the 'x11vnc \fB-remote\fR ...' -x11vnc command exits. You can often use the \fB-query\fR -command (see below) to see if the x11vnc server -processed your \fB-remote\fR command. -.IP -The default communication channel is that of X -properties (specifically X11VNC_REMOTE), and so this -command must be run with correct settings for DISPLAY -and possibly XAUTHORITY to connect to the X server -and set the property. Alternatively, use the \fB-display\fR -and \fB-auth\fR options to set them to the correct values. -The running server cannot use the \fB-novncconnect\fR option -because that disables the communication channel. -See below for alternate channels. -.IP -For example: 'x11vnc \fB-remote\fR stop' (which is the same as -\'x11vnc \fB-R\fR stop') will close down the x11vnc server. -\'x11vnc \fB-R\fR shared' will enable shared connections, and -\'x11vnc \fB-R\fR scale:3/4' will rescale the desktop. -.IP -To use a different name for the X11 property (e.g. to -have separate communication channels for multiple -x11vnc's on the same display) set the X11VNC_REMOTE -environment variable to the string you want, for -example: \fB-env\fR X11VNC_REMOTE=X11VNC_REMOTE_12345 -Both sides of the channel must use the same unique name. -.IP -To run a bunch of commands in a sequence use something -like: x11vnc \fB-R\fR 'script:firstcmd;secondcmd;...' -.IP -Use x11vnc \fB-R\fR script:file=/path/to/file to read commands -from a file (can be multi-line and use the comment '#' -character in the normal way. The ';' separator must -still be used to separate each command.) -.IP -To not try to contact another x11vnc process and instead -just run the command (or query) directly, prefix the -command with the string "DIRECT:" -.IP -.IP -The following \fB-remote/-R\fR commands are supported: -.IP -stop terminate the server, same as "quit" -"exit" or "shutdown". -.IP -ping see if the x11vnc server responds. -return is: ans=ping:<display> -.IP -ping:mystring as above, but use your own unique string. -return is: ans=ping:mystring:<xdisplay> -.IP -blacken try to push a black fb update to all -clients (due to timings a client -could miss it). Same as "zero", also -"zero:x1,y1,x2,y2" for a rectangle. -.IP -refresh send the entire fb to all clients. -.IP -reset recreate the fb, polling memory, etc. -.IP -id:windowid set \fB-id\fR window to "windowid". empty -or "root" to go back to root window -.IP -sid:windowid set \fB-sid\fR window to "windowid" -.IP -id_cmd:cmd cmds: raise, lower, map, unmap, iconify, -move:dXdY, resize:dWdH, geom:WxH+X+Y. dX -dY, dW, and dH must have a leading "+" -or "-" e.g.: move:-30+10 resize:+20+35 -also: wm_delete, wm_name:string and -icon_name:string. Also id_cmd:win=N:cmd -.IP -waitmapped wait until subwin is mapped. -.IP -nowaitmapped do not wait until subwin is mapped. -.IP -clip:WxH+X+Y set \fB-clip\fR mode to "WxH+X+Y" -.IP -flashcmap enable \fB-flashcmap\fR mode. -.IP -noflashcmap disable \fB-flashcmap\fR mode. -.IP -shiftcmap:n set \fB-shiftcmap\fR to n. -.IP -notruecolor enable \fB-notruecolor\fR mode. -.IP -truecolor disable \fB-notruecolor\fR mode. -.IP -overlay enable \fB-overlay\fR mode (if applicable). -.IP -nooverlay disable \fB-overlay\fR mode. -.IP -overlay_cursor in \fB-overlay\fR mode, enable cursor drawing. -.IP -overlay_nocursor disable cursor drawing. same as -nooverlay_cursor. -.IP -8to24 enable \fB-8to24\fR mode (if applicable). -.IP -no8to24 disable \fB-8to24\fR mode. -.IP -8to24_opts:str set the \fB-8to24\fR opts to "str". -.IP -24to32 enable \fB-24to32\fR mode (if applicable). -.IP -no24to32 disable \fB-24to32\fR mode. -.IP -visual:vis set \fB-visual\fR to "vis" -.IP -scale:frac set \fB-scale\fR to "frac" -.IP -scale_cursor:f set \fB-scale_cursor\fR to "f" -.IP -viewonly enable \fB-viewonly\fR mode. -.IP -noviewonly disable \fB-viewonly\fR mode. -.IP -shared enable \fB-shared\fR mode. -.IP -noshared disable \fB-shared\fR mode. -.IP -forever enable \fB-forever\fR mode. -.IP -noforever disable \fB-forever\fR mode. -.IP -timeout:n reset \fB-timeout\fR to n, if there are -currently no clients, exit unless one -connects in the next n secs. -.IP -tightfilexfer enable filetransfer for NEW clients. -.IP -notightfilexfer disable filetransfer for NEW clients. -.IP -ultrafilexfer enable filetransfer for clients. -.IP -noultrafilexfer disable filetransfer for clients. -.IP -rfbversion:n.m set \fB-rfbversion\fR for new clients. -.IP -http enable http client connections. -.IP -nohttp disable http client connections. -.IP -deny deny any new connections, same as "lock" -.IP -nodeny allow new connections, same as "unlock" -.IP -avahi enable avahi service advertising. -.IP -noavahi disable avahi service advertising. -.IP -mdns enable avahi service advertising. -.IP -nomdns disable avahi service advertising. -.IP -zeroconf enable avahi service advertising. -.IP -nozeroconf disable avahi service advertising. -.IP -connect:host do reverse connection to host, "host" -may be a comma separated list of hosts -or host:ports. See \fB-connect.\fR Passwords -required as with fwd connections. -See X11VNC_REVERSE_CONNECTION_NO_AUTH=1 -.IP -disconnect:host disconnect any clients from "host" -same as "close:host". Use host -"all" to close all current clients. -If you know the client internal hex ID, -e.g. 0x3 (returned by "\fB-query\fR \fIclients\fR" -and RFB_CLIENT_ID) you can use that too. -.IP -proxy:host:port set reverse connection proxy (empty to -disable). -.IP -allowonce:host For the next connection only, allow -connection from "host". In \fB-ssl\fR mode -two connections are allowed (i.e. Fetch -Cert) unless X11VNC_NO_SSL_ALLOW_TWICE=1 -.IP -allow:hostlist set \fB-allow\fR list to (comma separated) -"hostlist". See \fB-allow\fR and \fB-localhost.\fR -Do not use with \fB-allow\fR /path/to/file -Use "+host" to add a single host, and -use "\fB-host\fR" to delete a single host -.IP -localhost enable \fB-localhost\fR mode -.IP -nolocalhost disable \fB-localhost\fR mode -.IP -listen:str set \fB-listen\fR to str, empty to disable. -.IP -noipv6 enable \fB-noipv6\fR mode. -.IP -ipv6 disable \fB-noipv6\fR mode. -.IP -noipv4 enable \fB-noipv4\fR mode. -.IP -ipv4 disable \fB-noipv4\fR mode. -.IP -6 enable -6 IPv6 listening mode. -.IP -no6 disable -6 IPv6 listening mode. -.IP -lookup disable \fB-nolookup\fR mode. -.IP -nolookup enable \fB-nolookup\fR mode. -.IP -lookup disable \fB-nolookup\fR mode. -.IP -input:str set \fB-input\fR to "str", empty to disable. -.IP -grabkbd enable \fB-grabkbd\fR mode. -.IP -nograbkbd disable \fB-grabkbd\fR mode. -.IP -grabptr enable \fB-grabptr\fR mode. -.IP -nograbptr disable \fB-grabptr\fR mode. -.IP -grabalways enable \fB-grabalways\fR mode. -.IP -nograbalways disable \fB-grabalways\fR mode. -.IP -grablocal:n set \fB-grablocal\fR to n. -.IP -client_input:str set the K, M, B \fB-input\fR on a per-client -basis. select which client as for -disconnect, e.g. client_input:host:MB -or client_input:0x2:K -.IP -accept:cmd set \fB-accept\fR "cmd" (empty to disable). -.IP -afteraccept:cmd set \fB-afteraccept\fR (empty to disable). -.IP -gone:cmd set \fB-gone\fR "cmd" (empty to disable). -.IP -noshm enable \fB-noshm\fR mode. -.IP -shm disable \fB-noshm\fR mode (i.e. use shm). -.IP -flipbyteorder enable \fB-flipbyteorder\fR mode, you may need -to set noshm for this to do something. -.IP -noflipbyteorder disable \fB-flipbyteorder\fR mode. -.IP -onetile enable \fB-onetile\fR mode. (you may need to -set shm for this to do something) -.IP -noonetile disable \fB-onetile\fR mode. -.IP -solid enable \fB-solid\fR mode -.IP -nosolid disable \fB-solid\fR mode. -.IP -solid_color:color set \fB-solid\fR color (and apply it). -.IP -blackout:str set \fB-blackout\fR "str" (empty to disable). -See \fB-blackout\fR for the form of "str" -(basically: WxH+X+Y,...) -Use "+WxH+X+Y" to append a single -rectangle use "-WxH+X+Y" to delete one -.IP -xinerama enable \fB-xinerama\fR mode. (if applicable) -.IP -noxinerama disable \fB-xinerama\fR mode. -.IP -xtrap enable \fB-xtrap\fR input mode(if applicable) -.IP -noxtrap disable \fB-xtrap\fR input mode. -.IP -xrandr enable \fB-xrandr\fR mode. (if applicable) -.IP -noxrandr disable \fB-xrandr\fR mode. -.IP -xrandr_mode:mode set the \fB-xrandr\fR mode to "mode". -.IP -rotate:mode set the \fB-rotate\fR mode to "mode". -.IP -padgeom:WxH set \fB-padgeom\fR to WxH (empty to disable) -If WxH is "force" or "do" the padded -geometry fb is immediately applied. -.IP -quiet enable \fB-quiet\fR mode. -.IP -noquiet disable \fB-quiet\fR mode. -.IP -modtweak enable \fB-modtweak\fR mode. -.IP -nomodtweak enable \fB-nomodtweak\fR mode. -.IP -xkb enable \fB-xkb\fR modtweak mode. -.IP -noxkb disable \fB-xkb\fR modtweak mode. -.IP -capslock enable \fB-capslock\fR mode. -.IP -nocapslock disable \fB-capslock\fR mode. -.IP -skip_lockkeys enable \fB-skip_lockkeys\fR mode. -.IP -noskip_lockkeys disable \fB-skip_lockkeys\fR mode. -.IP -skip_keycodes:str enable \fB-xkb\fR \fB-skip_keycodes\fR "str". -.IP -sloppy_keys enable \fB-sloppy_keys\fR mode. -.IP -nosloppy_keys disable \fB-sloppy_keys\fR mode. -.IP -skip_dups enable \fB-skip_dups\fR mode. -.IP -noskip_dups disable \fB-skip_dups\fR mode. -.IP -add_keysyms enable \fB-add_keysyms\fR mode. -.IP -noadd_keysyms stop adding keysyms. those added will -still be removed at exit. -.IP -clear_mods enable \fB-clear_mods\fR mode and clear them. -.IP -noclear_mods disable \fB-clear_mods\fR mode. -.IP -clear_keys enable \fB-clear_keys\fR mode and clear them. -.IP -noclear_keys disable \fB-clear_keys\fR mode. -.IP -clear_locks do the clear_locks action. -.IP -clear_all do the clear_all action. -.IP -keystate have x11vnc print current keystate. -.IP -remap:str set \fB-remap\fR "str" (empty to disable). -See \fB-remap\fR for the form of "str" -(basically: key1-key2,key3-key4,...) -Use "+key1-key2" to append a single -keymapping, use "-key1-key2" to delete. -.IP -norepeat enable \fB-norepeat\fR mode. -.IP -repeat disable \fB-norepeat\fR mode. -.IP -nofb enable \fB-nofb\fR mode. -.IP -fb disable \fB-nofb\fR mode. -.IP -bell enable bell (if supported). -.IP -nobell disable bell. -.IP -sendbell ring the bell now. -.IP -nosel enable \fB-nosel\fR mode. -.IP -sel disable \fB-nosel\fR mode. -.IP -noprimary enable \fB-noprimary\fR mode. -.IP -primary disable \fB-noprimary\fR mode. -.IP -nosetprimary enable \fB-nosetprimary\fR mode. -.IP -setprimary disable \fB-nosetprimary\fR mode. -.IP -noclipboard enable \fB-noclipboard\fR mode. -.IP -clipboard disable \fB-noclipboard\fR mode. -.IP -nosetclipboard enable \fB-nosetclipboard\fR mode. -.IP -setclipboard disable \fB-nosetclipboard\fR mode. -.IP -seldir:str set \fB-seldir\fR to "str" -.IP -resend_cutbuffer resend the most recent CUTBUFFER0 copy -.IP -resend_clipboard resend the most recent CLIPBOARD copy -.IP -resend_primary resend the most recent PRIMARY copy -.IP -cursor:mode enable \fB-cursor\fR "mode". -.IP -show_cursor enable showing a cursor. -.IP -noshow_cursor disable showing a cursor. (same as -"nocursor") -.IP -cursor_drag enable cursor changes during drag. -.IP -nocursor_drag disable cursor changes during drag. -.IP -arrow:n set \fB-arrow\fR to alternate n. -.IP -xfixes enable xfixes cursor shape mode. -.IP -noxfixes disable xfixes cursor shape mode. -.IP -alphacut:n set \fB-alphacut\fR to n. -.IP -alphafrac:f set \fB-alphafrac\fR to f. -.IP -alpharemove enable \fB-alpharemove\fR mode. -.IP -noalpharemove disable \fB-alpharemove\fR mode. -.IP -alphablend disable \fB-noalphablend\fR mode. -.IP -noalphablend enable \fB-noalphablend\fR mode. -.IP -cursorshape disable \fB-nocursorshape\fR mode. -.IP -nocursorshape enable \fB-nocursorshape\fR mode. -.IP -cursorpos disable \fB-nocursorpos\fR mode. -.IP -nocursorpos enable \fB-nocursorpos\fR mode. -.IP -xwarp enable \fB-xwarppointer\fR mode. -.IP -noxwarp disable \fB-xwarppointer\fR mode. -.IP -always_inject enable \fB-always_inject\fR mode. -.IP -noalways_inject disable \fB-always_inject\fR mode. -.IP -buttonmap:str set \fB-buttonmap\fR "str", empty to disable -.IP -dragging disable \fB-nodragging\fR mode. -.IP -nodragging enable \fB-nodragging\fR mode. -.IP -ncache reenable \fB-ncache\fR mode. -.IP -noncache disable \fB-ncache\fR mode. -.IP -ncache_size:n set \fB-ncache\fR size to n. -.IP -ncache_cr enable \fB-ncache_cr\fR mode. -.IP -noncache_cr disable \fB-ncache_cr\fR mode. -.IP -ncache_no_moveraise enable no_moveraise mode. -.IP -noncache_no_moveraise disable no_moveraise mode. -.IP -ncache_no_dtchange enable ncache_no_dtchange mode. -.IP -noncache_no_dtchange disable ncache_no_dtchange mode. -.IP -ncache_old_wm enable ncache_old_wm mode. -.IP -noncache_old_wm disable ncache_old_wm mode. -.IP -ncache_no_rootpixmap enable ncache_no_rootpixmap. -.IP -noncache_no_rootpixmap disable ncache_no_rootpixmap. -.IP -ncache_reset_rootpixmap recheck the root pixmap, ncrp -.IP -ncache_keep_anims enable ncache_keep_anims. -.IP -noncache_keep_anims disable ncache_keep_anims. -.IP -ncache_pad:n set \fB-ncache_pad\fR to n. -.IP -wireframe enable \fB-wireframe\fR mode. same as "wf" -.IP -nowireframe disable \fB-wireframe\fR mode. same as "nowf" -.IP -wireframe:str enable \fB-wireframe\fR mode string. -.IP -wireframe_mode:str enable \fB-wireframe\fR mode string. -.IP -wireframelocal enable wireframelocal. same as "wfl" -.IP -nowireframe disable wireframelocal. same as "nowfl" -.IP -wirecopyrect:str set \fB-wirecopyrect\fR string. same as "wcr:" -.IP -scrollcopyrect:str set \fB-scrollcopyrect\fR string. same "scr" -.IP -noscrollcopyrect disable \fB-scrollcopyrect__mode_.\fR "noscr" -.IP -scr_area:n set \fB-scr_area\fR to n -.IP -scr_skip:list set \fB-scr_skip\fR to "list" -.IP -scr_inc:list set \fB-scr_inc\fR to "list" -.IP -scr_keys:list set \fB-scr_keys\fR to "list" -.IP -scr_term:list set \fB-scr_term\fR to "list" -.IP -scr_keyrepeat:str set \fB-scr_keyrepeat\fR to "str" -.IP -scr_parms:str set \fB-scr_parms\fR parameters. -.IP -fixscreen:str set \fB-fixscreen\fR to "str". -.IP -noxrecord disable all use of RECORD extension. -.IP -xrecord enable use of RECORD extension. -.IP -reset_record reset RECORD extension (if avail.) -.IP -pointer_mode:n set \fB-pointer_mode\fR to n. same as "pm" -.IP -input_skip:n set \fB-input_skip\fR to n. -.IP -allinput enable use of \fB-allinput\fR mode. -.IP -noallinput disable use of \fB-allinput\fR mode. -.IP -input_eagerly enable use of \fB-input_eagerly\fR mode. -.IP -noinput_eagerly disable use of \fB-input_eagerly\fR mode. -.IP -ssltimeout:n set \fB-ssltimeout\fR to n. -.IP -speeds:str set \fB-speeds\fR to str. -.IP -wmdt:str set \fB-wmdt\fR to str. -.IP -debug_pointer enable \fB-debug_pointer,\fR same as "dp" -.IP -nodebug_pointer disable \fB-debug_pointer,\fR same as "nodp" -.IP -debug_keyboard enable \fB-debug_keyboard,\fR same as "dk" -.IP -nodebug_keyboard disable \fB-debug_keyboard,\fR same as "nodk" -.IP -keycode:n inject keystroke 'keycode' (xmodmap \fB-pk)\fR -.IP -keycode:n,down inject 'keycode' (down=0,1) -.IP -keysym:str inject keystroke 'keysym' (number/name) -.IP -keysym:str,down inject 'keysym' (down=0,1) -.IP -ptr:x,y,mask inject pointer event x, y, button-mask -.IP -fakebuttonevent:button,down direct XTestFakeButtonEvent. -.IP -sleep:t sleep floating point time t. -.IP -get_xprop:p get X property named 'p'. -.IP -set_xprop:p:val set X property named 'p' to 'val'. -p -> id=NNN:p for hex/dec window id. -.IP -wininfo:id get info about X window id. use 'root' -for root window, use +id for children. -.IP -grab_state get state of pointer and keyboard grab. -.IP -pointer_pos print XQueryPointer x,y cursor position. -.IP -pointer_x print XQueryPointer x cursor position. -.IP -pointer_y print XQueryPointer y cursor position. -.IP -pointer_same print XQueryPointer ptr on same screen. -.IP -pointer_root print XQueryPointer curr ptr rootwin. -.IP -pointer_mask print XQueryPointer button and mods mask -.IP -mouse_x print x11vnc's idea of cursor position. -.IP -mouse_y print x11vnc's idea of cursor position. -.IP -noop do nothing. -.IP -defer:n set \fB-defer\fR to n ms,same as deferupdate:n -.IP -wait:n set \fB-wait\fR to n ms. -.IP -extra_fbur:n set \fB-extra_fbur\fR to n. -.IP -wait_ui:f set \fB-wait_ui\fR factor to f. -.IP -setdefer:n set \fB-setdefer\fR to \fB-2,-1,0,1,\fR or 2. -.IP -wait_bog disable \fB-nowait_bog\fR mode. -.IP -nowait_bog enable \fB-nowait_bog\fR mode. -.IP -slow_fb:f set \fB-slow_fb\fR to f seconds. -.IP -xrefresh:f set \fB-xrefresh\fR to f seconds. -.IP -readtimeout:n set read timeout to n seconds. -.IP -nap enable \fB-nap\fR mode. -.IP -nonap disable \fB-nap\fR mode. -.IP -sb:n set \fB-sb\fR to n s, same as screen_blank:n -.IP -fbpm disable \fB-nofbpm\fR mode. -.IP -nofbpm enable \fB-nofbpm\fR mode. -.IP -dpms disable \fB-nodpms\fR mode. -.IP -nodpms enable \fB-nodpms\fR mode. -.IP -forcedpms enable \fB-forcedpms\fR mode. -.IP -noforcedpms disable \fB-forcedpms\fR mode. -.IP -clientdpms enable \fB-clientdpms\fR mode. -.IP -noclientdpms disable \fB-clientdpms\fR mode. -.IP -noserverdpms enable \fB-noserverdpms\fR mode. -.IP -serverdpms disable \fB-noserverdpms\fR mode. -.IP -noultraext enable \fB-noultraext\fR mode. -.IP -ultraext disable \fB-noultraext\fR mode. -.IP -chatwindow enable local chatwindow mode. -.IP -nochatwindow disable local chatwindow mode. -.IP -chaton begin chat using local window. -.IP -chatoff end chat using local window. -.IP -xdamage enable xdamage polling hints. -.IP -noxdamage disable xdamage polling hints. -.IP -xd_area:A set \fB-xd_area\fR max pixel area to "A" -.IP -xd_mem:f set \fB-xd_mem\fR remembrance to "f" -.IP -fs:frac set \fB-fs\fR fraction to "frac", e.g. 0.5 -.IP -gaps:n set \fB-gaps\fR to n. -.IP -grow:n set \fB-grow\fR to n. -.IP -fuzz:n set \fB-fuzz\fR to n. -.IP -snapfb enable \fB-snapfb\fR mode. -.IP -nosnapfb disable \fB-snapfb\fR mode. -.IP -rawfb:str set \fB-rawfb\fR mode to "str". -.IP -uinput_accel:f set uinput_accel to f. -.IP -uinput_thresh:n set uinput_thresh to n. -.IP -uinput_reset:n set uinput_reset to n ms. -.IP -uinput_always:n set uinput_always to 1/0. -.IP -progressive:n set LibVNCServer \fB-progressive\fR slice -height parameter to n. -.IP -desktop:str set \fB-desktop\fR name to str for new clients. -.IP -rfbport:n set \fB-rfbport\fR to n. -.IP -macnosaver enable \fB-macnosaver\fR mode. -.IP -macsaver disable \fB-macnosaver\fR mode. -.IP -macnowait enable \fB-macnowait\fR mode. -.IP -macwait disable \fB-macnowait\fR mode. -.IP -macwheel:n set \fB-macwheel\fR to n. -.IP -macnoswap enable \fB-macnoswap\fR mouse button mode. -.IP -macswap disable \fB-macnoswap\fR mouse button mode. -.IP -macnoresize enable \fB-macnoresize\fR mode. -.IP -macresize disable \fB-macnoresize\fR mode. -.IP -maciconanim:n set \fB-maciconanim\fR to n. -.IP -macmenu enable \fB-macmenu\fR mode. -.IP -macnomenu disable \fB-macmenu\fR mode. -.IP -macuskbd enable \fB-macuskbd\fR mode. -.IP -macnouskbd disable \fB-macuskbd\fR mode. -.IP -httpport:n set \fB-httpport\fR to n. -.IP -httpdir:dir set \fB-httpdir\fR to dir (and enable http). -.IP -enablehttpproxy enable \fB-enablehttpproxy\fR mode. -.IP -noenablehttpproxy disable \fB-enablehttpproxy\fR mode. -.IP -alwaysshared enable \fB-alwaysshared\fR mode. -.IP -noalwaysshared disable \fB-alwaysshared\fR mode. -(may interfere with other options) -.IP -nevershared enable \fB-nevershared\fR mode. -.IP -nonevershared disable \fB-nevershared\fR mode. -(may interfere with other options) -.IP -dontdisconnect enable \fB-dontdisconnect\fR mode. -.IP -nodontdisconnect disable \fB-dontdisconnect\fR mode. -(may interfere with other options) -.IP -debug_xevents enable debugging X events. -.IP -nodebug_xevents disable debugging X events. -.IP -debug_xdamage enable debugging X DAMAGE mechanism. -.IP -nodebug_xdamage disable debugging X DAMAGE mechanism. -.IP -debug_wireframe enable debugging wireframe mechanism. -.IP -nodebug_wireframe disable debugging wireframe mechanism. -.IP -debug_scroll enable debugging scrollcopy mechanism. -.IP -nodebug_scroll disable debugging scrollcopy mechanism. -.IP -debug_tiles enable \fB-debug_tiles\fR -.IP -nodebug_tiles disable \fB-debug_tiles\fR -.IP -debug_grabs enable \fB-debug_grabs\fR -.IP -nodebug_grabs disable \fB-debug_grabs\fR -.IP -debug_sel enable \fB-debug_sel\fR -.IP -nodebug_sel disable \fB-debug_sel\fR -.IP -debug_ncache enable \fB-debug_ncache\fR -.IP -nodebug_ncache disable \fB-debug_ncache\fR -.IP -dbg enable \fB-dbg\fR crash shell -.IP -nodbg disable \fB-dbg\fR crash shell -.IP -.IP -noremote disable the \fB-remote\fR command processing, -it cannot be turned back on. -.IP -.IP -bcx_xattach:str This remote control command is for -use with the BARCO xattach program or the x2x program. -Both of these programs are for 'pointer and keyboard' -sharing between separate X displays. In general the -two displays are usually nearby, e.g. on the same desk, -and this allows the user to share a single pointer and -keyboard between them. The user moves the mouse to -an edge and then the mouse pointer appears to 'jump' -to the other display screen. Thus it emulates what a -single X server would do for two screens (e.g. :0.0 and -:0.1) The illusion of a single Xserver with multiple -screens is achieved by forwarding events to the 2nd -one via the XTEST extension. -.IP -What the x11vnc bcx_xattach command does is to perform -some pointer movements to try to INDUCE xattach/x2x -to 'jump' to the other display. In what follows the -\'master' display refers to the one that when it has -\'focus' it is basically doing nothing besides watching -for the mouse to go over an edge. The 'slave' -display refers to the one to which the mouse and -keyboard is redirected to once an edge in the master -has been crossed. Note that the x11vnc executing the -bcx_xattach command MUST be the one connected to the -*master* display. -.IP -Also note that when input is being redirected (via -XTEST) from the master display to the slave display, -the master display's pointer and keyboard are *grabbed* -by xattach/x2x. x11vnc can use this info to verify that -the master/slave mode change has taken place correctly. -If you specify the "ifneeded" option (see below) -and the initial grab state is that of the desired -final state, then no pointer movements are injected -and "DONE,GRAB_OK" is returned. -.IP -"str" must contain one of "up", "down", "left", -or "right" to indicate the direction of the 'jump'. -"str" must also contain one of "master_to_slave" -or "slave_to_master" to indicate the type of mode -change induced by the jump. Use "M2S" and "S2M" -as shorter aliases. -.IP -"str" may be a "+" separated list of additional -tuning options. The "shift=n" option indicates an -offset shift position away from (0,0) (default 20). -"final=x+y" specifies the final position of the cursor -at the end of the normal move sequence; default 30+30. -"extra_move=x+y" means to do one more pointer move -after "final" to x+y. "dt=n" sets the sleep time -in milliseconds between pointer moves (default: 40ms) -"retry=n" specifies the maximum number of retries if -the grab state change fails. "ifneeded" means to not -apply the pointer movements if the initial grab state is -that of the desired final state. "nograbcheck" means -to not check if the grab state changed as expected and -only apply the pointer movements (default is to check -the grab states.) -.IP -If you do not specify "up", etc., to bcx_xattach -nothing will be attempted and the command returns -the string FAIL,NO_DIRECTION_SPECIFIED. If you do -not specify "master_to_slave" or "M2S", etc., to -bcx_xattach nothing will be attempted and the command -returns the string FAIL,NO_MODE_CHANGE_SPECIFIED. -.IP -Otherwise, the returned string will contain "DONE". -It will be "DONE,GRAB_OK" if the grab state changed -as expected (or if "ifneeded" was supplied and -the initial grab state was already the desired -one.) If the initial grab state was incorrect, -but the final grab state was correct then it is -"DONE,GRAB_FAIL_INIT". If the initial grab state -was correct, but the final grab state was incorrect -then it is "DONE,GRAB_FAIL_FINAL". If both are -incorrect it will be "DONE,GRAB_FAIL". Under grab -failure the string will be followed by ":p1,k1-p2,k2" -where p1,k1 indicates the initial pointer and keyboard -grab states and p2,k2 the final ones. If GRAB_FAIL or -GRAB_FAIL_FINAL occurs, the action will be retried up -to 3 times; trying to reset the state and sleeping a -bit between each try. Set retry=n to adjust the number -of retries, zero to disable retries. -.IP -Examples: -\fB-R\fR bcx_xattach:down+M2S -\fB-R\fR bcx_xattach:up+S2M -\fB-R\fR bcx_xattach:up+S2M+nograbcheck+dt=30 -\fB-R\fR bcx_xattach:down+M2S+extra_move=100+100 -.IP -or use \fB-Q\fR instead of \fB-R\fR to retrieve the result text. -.IP -End of the bcx_xattach:str description. -.IP -The -.IR vncconnect (1) -command from standard VNC -distributions may also be used if string is prefixed -with "cmd=" E.g. 'vncconnect cmd=stop'. Under some -circumstances -.IR xprop (1) -can used if it supports \fB-set\fR -(see the FAQ). -.IP -If "\fB-connect\fR \fI/path/to/file\fR" has been supplied to the -running x11vnc server then that file can be used as a -communication channel (this is the only way to remote -control one of many x11vnc's polling the same X display) -Simply run: 'x11vnc \fB-connect\fR /path/to/file \fB-remote\fR ...' -or you can directly write to the file via something -like: "echo cmd=stop > /path/to/file", etc. -.PP -\fB-query\fR \fIvariable\fR -.IP -Like \fB-remote,\fR except just query the value of -\fIvariable\fR. "\fB-Q\fR" is an alias for "\fB-query\fR". -Multiple queries can be done by separating variables -by commas, e.g. \fB-query\fR var1,var2. The results come -back in the form ans=var1:value1,ans=var2:value2,... -to the standard output. If a variable is read-only, -it comes back with prefix "aro=" instead of "ans=". -.IP -Some \fB-remote\fR commands are pure actions that do not make -sense as variables, e.g. "stop" or "disconnect", in -these cases the value returned is "N/A". To direct a -query straight to the X11VNC_REMOTE property or connect -file use "qry=..." instead of "cmd=..." -.IP -ans= stop quit exit shutdown ping resend_cutbuffer -resend_clipboard resend_primary blacken zero refresh -reset close disconnect id_cmd id sid waitmapped -nowaitmapped clip flashcmap noflashcmap shiftcmap -truecolor notruecolor overlay nooverlay overlay_cursor -overlay_yescursor nooverlay_nocursor nooverlay_cursor -nooverlay_yescursor overlay_nocursor 8to24 no8to24 -8to24_opts 24to32 no24to32 visual scale scale_cursor -viewonly noviewonly shared noshared forever noforever -once timeout tightfilexfer notightfilexfer ultrafilexfer -noultrafilexfer rfbversion deny lock nodeny unlock avahi -mdns zeroconf noavahi nomdns nozeroconf connect proxy -allowonce allow noipv6 ipv6 noipv4 ipv4 no6 6 localhost -nolocalhost listen lookup nolookup accept afteraccept -gone shm noshm flipbyteorder noflipbyteorder onetile -noonetile solid_color solid nosolid blackout xinerama -noxinerama xtrap noxtrap xrandr noxrandr xrandr_mode -rotate padgeom quiet q noquiet modtweak nomodtweak xkb -noxkb capslock nocapslock skip_lockkeys noskip_lockkeys -skip_keycodes sloppy_keys nosloppy_keys skip_dups -noskip_dups add_keysyms noadd_keysyms clear_mods -noclear_mods clear_keys noclear_keys clear_all -clear_locks keystate remap repeat norepeat fb nofb bell -nobell sendbell sel nosel primary noprimary setprimary -nosetprimary clipboard noclipboard setclipboard -nosetclipboard seldir cursorshape nocursorshape -cursorpos nocursorpos cursor_drag nocursor_drag cursor -show_cursor noshow_cursor nocursor arrow xfixes noxfixes -xdamage noxdamage xd_area xd_mem alphacut alphafrac -alpharemove noalpharemove alphablend noalphablend -xwarppointer xwarp noxwarppointer noxwarp always_inject -noalways_inject buttonmap dragging nodragging ncache_cr -noncache_cr ncache_no_moveraise noncache_no_moveraise -ncache_no_dtchange noncache_no_dtchange -ncache_no_rootpixmap noncache_no_rootpixmap -ncache_reset_rootpixmap ncrp ncache_keep_anims -noncache_keep_anims ncache_old_wm noncache_old_wm -ncache_pad ncache noncache ncache_size debug_ncache -nodebug_ncache wireframe_mode wireframe wf nowireframe -nowf wireframelocal wfl nowireframelocal nowfl -wirecopyrect wcr nowirecopyrect nowcr scr_area -scr_skip scr_inc scr_keys scr_term scr_keyrepeat -scr_parms scrollcopyrect scr noscrollcopyrect -noscr fixscreen noxrecord xrecord reset_record -pointer_mode pm input_skip allinput noallinput -input_eagerly noinput_eagerly input grabkbd nograbkbd -grabptr nograbptr grabalways nograbalways grablocal -client_input ssltimeout speeds wmdt debug_pointer dp -nodebug_pointer nodp debug_keyboard dk nodebug_keyboard -nodk keycode keysym ptr fakebuttonevent sleep get_xprop -set_xprop wininfo bcx_xattach deferupdate defer -setdefer extra_fbur wait_ui wait_bog nowait_bog -slow_fb xrefresh wait readtimeout nap nonap sb -screen_blank fbpm nofbpm dpms nodpms clientdpms -noclientdpms forcedpms noforcedpms noserverdpms -serverdpms noultraext ultraext chatwindow nochatwindow -chaton chatoff fs gaps grow fuzz snapfb nosnapfb -rawfb uinput_accel uinput_thresh uinput_reset -uinput_always progressive rfbport http nohttp httpport -httpdir enablehttpproxy noenablehttpproxy alwaysshared -noalwaysshared nevershared noalwaysshared dontdisconnect -nodontdisconnect desktop debug_xevents nodebug_xevents -debug_xevents debug_xdamage nodebug_xdamage -debug_xdamage debug_wireframe nodebug_wireframe -debug_wireframe debug_scroll nodebug_scroll debug_scroll -debug_tiles dbt nodebug_tiles nodbt debug_tiles -debug_grabs nodebug_grabs debug_sel nodebug_sel dbg -nodbg macnosaver macsaver nomacnosaver macnowait macwait -nomacnowait macwheel macnoswap macswap nomacnoswap -macnoresize macresize nomacnoresize maciconanim macmenu -macnomenu nomacmenu macuskbd nomacuskbd noremote -.IP -aro= noop display vncdisplay icon_mode autoport -loop loopbg desktopname guess_desktop guess_dbus -http_url auth xauth users rootshift clipshift scale_str -scaled_x scaled_y scale_numer scale_denom scale_fac_x -scale_fac_y scaling_blend scaling_nomult4 scaling_pad -scaling_interpolate inetd privremote unsafe safer nocmds -passwdfile unixpw unixpw_nis unixpw_list ssl ssl_pem -sslverify stunnel stunnel_pem https httpsredir usepw -using_shm logfile o flag rmflag rc norc h help V version -lastmod bg sigpipe threads readrate netrate netlatency -pipeinput clients client_count pid ext_xtest ext_xtrap -ext_xrecord ext_xkb ext_xshm ext_xinerama ext_overlay -ext_xfixes ext_xdamage ext_xrandr rootwin num_buttons -button_mask mouse_x mouse_y grab_state pointer_pos -pointer_x pointer_y pointer_same pointer_root -pointer_mask bpp depth indexed_color dpy_x dpy_y wdpy_x -wdpy_y off_x off_y cdpy_x cdpy_y coff_x coff_y rfbauth -passwd viewpasswd -.PP -\fB-QD\fR \fIvariable\fR -.IP -Just like \fB-query\fR variable, but returns the default -value for that parameter (no running x11vnc server -is consulted) -.PP -\fB-sync\fR -.IP -By default \fB-remote\fR commands are run asynchronously, that -is, the request is posted and the program immediately -exits. Use \fB-sync\fR to have the program wait for an -acknowledgement from the x11vnc server that command was -processed (somehow). On the other hand \fB-query\fR requests -are always processed synchronously because they have -to wait for the answer. -.IP -Also note that if both \fB-remote\fR and \fB-query\fR requests are -supplied on the command line, the \fB-remote\fR is processed -first (synchronously: no need for \fB-sync),\fR and then -the \fB-query\fR request is processed in the normal way. -This allows for a reliable way to see if the \fB-remote\fR -command was processed by querying for any new settings. -Note however that there is timeout of a few seconds -(see the next paragraph) so if the x11vnc takes longer -than that to process the requests the requester will -think that a failure has taken place. -.IP -The default is to wait 3.5 seconds. Or if cmd=stop -only 1.0 seconds. If cmd matches 'script:' then it -will wait up to 10.0 seconds. Set X11VNC_SYNC_TIMEOUT -to the number of seconds you want it to wait. -.PP -\fB-query_retries\fR \fIstr\fR -.IP -If a query fails to get a response from an x11vnc -server, retry up to n times. \fIstr\fR is specified as -n[:t][/match] Optionally the delay between tries may -be specified by "t" a floating point time (default -0.5 seconds.) Note: the response is not checked for -validity or whether it corresponds to the query sent. -The query "ping:mystring" may be used to help uniquely -identify the query. Optionally, a matching string after -a "/" will be used to check the result text. Up to -n retries will take place until the matching string is -found in the output text. If the match string is never -found the program's exit code is 1; if the match is -found it exits with 0. Note that there may be stdout -printed for each retry (i.e. multiple lines printed -out to stdout.) -Example: \fB-query_retries\fR 4:1.5/grab_state -.PP -\fB-remote_prefix\fR \fIstr\fR -.IP -Enable a remote-control communication channel for -connected VNC clients. str is a non-empty string. If a -VNC client sends rfbCutText having the prefix \fIstr\fR -then the part after it is processed as though it were -sent via 'x11vnc \fB-remote\fR ...'. If it begins with -neither 'cmd=' nor 'qry=' then 'qry=' is assumed. -Any corresponding output text for that remote control -command is sent back to all client as rfbCutText. -The returned output is also prefixed with \fIstr\fR. -Example: \fB-remote_prefix\fR DO_THIS: -.IP -Note that enabling \fB-remote_prefix\fR allows the remote -VNC viewers to run x11vnc \fB-remote\fR commands. Do not -use this option if they are not to be trusted. -.PP -\fB-noremote,\fR \fB-yesremote\fR -.IP -Do not process any remote control commands or queries. -Do process remote control commands or queries. -Default: \fB-yesremote\fR -.IP -A note about security wrt remote control commands. -If someone can connect to the X display and change -the property X11VNC_REMOTE, then they can remotely -control x11vnc. Normally access to the X display is -protected. Note that if they can modify X11VNC_REMOTE -on the X server, they have enough permissions to also -run their own x11vnc and thus have complete control -of the desktop. If the "\fB-connect\fR \fI/path/to/file\fR" -channel is being used, obviously anyone who can write -to /path/to/file can remotely control x11vnc. So be -sure to protect the X display and that file's write -permissions. See \fB-privremote\fR below. -.IP -If you are paranoid and do not think \fB-noremote\fR is -enough, to disable the X11VNC_REMOTE property channel -completely use \fB-novncconnect,\fR or use the \fB-safer\fR option -that shuts many things off. -.PP -\fB-unsafe\fR -.IP -A few remote commands are disabled by default -(currently: id:pick, accept:<cmd>, gone:<cmd>, and -rawfb:setup:<cmd>) because they are associated with -running external programs. If you specify \fB-unsafe,\fR then -these remote-control commands are allowed. Note that -you can still specify these parameters on the command -line, they just cannot be invoked via remote-control. -.PP -\fB-safer\fR -.IP -Equivalent to: \fB-novncconnect\fR \fB-noremote\fR and prohibiting -\fB-gui\fR and the \fB-connect\fR file. Shuts off communcation -channels. -.PP -\fB-privremote\fR -.IP -Perform some sanity checks and disable remote-control -commands if it appears that the X DISPLAY and/or -connectfile can be accessed by other users. Once -remote-control is disabled it cannot be turned back on. -.PP -\fB-nocmds\fR -.IP -No external commands (e.g. -.IR system (3) -, -.IR popen (3) -, -.IR exec (3) -) -will be run at all. -.PP -\fB-allowedcmds\fR \fIlist\fR -.IP -\fIlist\fR contains a comma separated list of the only -external commands that can be run. The full list of -associated options is: -.IP -stunnel, ssl, unixpw, WAIT, zeroconf, id, accept, -afteraccept, gone, pipeinput, v4l-info, rawfb-setup, -dt, gui, ssh, storepasswd, passwdfile, custom_passwd, -findauth, crash. -.IP -See each option's help to learn the associated external -command. Note that the \fB-nocmds\fR option takes precedence -and disables all external commands. -.PP -\fB-deny_all\fR -.IP -For use with \fB-remote\fR nodeny: start out denying all -incoming clients until "\fB-remote\fR \fInodeny\fR" is used to -let them in. -.PP -These options are passed to LibVNCServer: -.PP -\fB-rfbport\fR \fIport\fR -.IP -TCP port for RFB protocol -.PP -\fB-rfbwait\fR \fItime\fR -.IP -max time in ms to wait for RFB client -.PP -\fB-rfbauth\fR \fIpasswd-file\fR -.IP -use authentication on RFB protocol -(use 'x11vnc \fB-storepasswd\fR pass file' to create a password file) -.PP -\fB-rfbversion\fR \fI3.x\fR -.IP -Set the version of the RFB we choose to advertise -.PP -\fB-permitfiletransfer\fR -.IP -permit file transfer support -.PP -\fB-passwd\fR \fIplain-password\fR -.IP -use authentication -(use plain-password as password, USE AT YOUR RISK) -.PP -\fB-deferupdate\fR \fItime\fR -.IP -time in ms to defer updates (default 40) -.PP -\fB-deferptrupdate\fR \fItime\fR -.IP -time in ms to defer pointer updates (default none) -.PP -\fB-desktop\fR \fIname\fR -.IP -VNC desktop name (default "LibVNCServer") -.PP -\fB-alwaysshared\fR -.IP -always treat new clients as shared -.PP -\fB-nevershared\fR -.IP -never treat new clients as shared -.PP -\fB-dontdisconnect\fR -.IP -don't disconnect existing clients when a new non-shared -connection comes in (refuse new connection instead) -.PP -\fB-httpdir\fR \fIdir-path\fR -.IP -enable http server using dir-path home -.PP -\fB-httpport\fR \fIportnum\fR -.IP -use portnum for http connection -.PP -\fB-enablehttpproxy\fR -.IP -enable http proxy support -.PP -\fB-progressive\fR \fIheight\fR -.IP -enable progressive updating for slow links -.PP -\fB-listen\fR \fIipaddr\fR -.IP -listen for connections only on network interface with -addr ipaddr. '-listen localhost' and hostname work too. -.PP -libvncserver-tight-extension options: -.PP -\fB-disablefiletransfer\fR -.IP -disable file transfer -.PP -\fB-ftproot\fR \fIstring\fR -.IP -set ftp root -.SH "FILES" -.IR $HOME/.x11vncrc , -.IR $HOME/.Xauthority -.SH "ENVIRONMENT" -.IR DISPLAY , -.IR XAUTHORITY , -.IR HOME -.PP -The following are set for the auxiliary commands -run by \fB-accept\fR, \fB-gone\fR and other cases: -.PP -.IR RFB_CLIENT_IP , -.IR RFB_CLIENT_PORT , -.IR RFB_SERVER_IP , -.IR RFB_SERVER_PORT , -.IR RFB_X11VNC_PID , -.IR RFB_CLIENT_ID , -.IR RFB_CLIENT_COUNT , -.IR RFB_MODE -.IR RFB_STATE -.IR RFB_LOGIN_VIEWONLY -.IR RFB_LOGIN_TIME -.IR RFB_CURRENT_TIME -.IR RFB_USERNAME -.IR RFB_SSL_CLIENT_CERT -.SH "SEE ALSO" -.IR vncviewer (1), -.IR vncpasswd (1), -.IR vncconnect (1), -.IR vncserver (1), -.IR Xvnc (1), -.IR xev (1), -.IR xdpyinfo (1), -.IR xwininfo (1), -.IR xprop (1), -.IR xmodmap (1), -.IR xrandr (1), -.IR Xserver (1), -.IR xauth (1), -.IR xhost (1), -.IR Xsecurity (7), -.IR xmessage (1), -.IR XGetImage (3X11), -.IR ipcrm (1), -.IR inetd (1), -.IR xdm (1), -.IR gdm (1), -.IR kdm (1), -.IR ssh (1), -.IR stunnel (8), -.IR su (1), -.IR http://www.tightvnc.com , -.IR http://www.realvnc.com , -.IR http://www.karlrunge.com/x11vnc/ , -.IR http://www.karlrunge.com/x11vnc/#faq -.SH AUTHORS -x11vnc was written by Karl J. Runge <runge@karlrunge.com>, -it is part of the LibVNCServer project <http://sf.net/projects/libvncserver>. -This manual page is based one the one written by Ludovic Drolez -<ldrolez@debian.org>, for the Debian project (both may be used by others). |
