| .\" 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). |