You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
5888 lines
211 KiB
5888 lines
211 KiB
.\" This file was automatically generated from x11vnc -help output.
|
|
.TH X11VNC "1" "January 2009" "x11vnc " "User Commands"
|
|
.SH NAME
|
|
x11vnc - allow VNC connections to real X11 displays
|
|
version: 0.9.7, lastmod: 2009-01-11
|
|
.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
|
|
.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.
|
|
.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-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.
|
|
.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-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 appear to work, 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:
|
|
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
|
|
.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.
|
|
.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.
|
|
.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
|
|
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.
|
|
.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
|
|
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
|
|
.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
|
|
.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.
|
|
.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
|
|
.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.
|
|
.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-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-unixpw\fR \fI[list]\fR
|
|
.IP
|
|
Use Unix username and password authentication. x11vnc
|
|
uses 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 25 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
|
|
carefully. 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 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.
|
|
.IP
|
|
Note that use of \fB-localhost\fR with
|
|
.IR ssh (1)
|
|
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
|
|
Set UNIXPW_DISABLE_LOCALHOST=1 to disable the \fB-localhost\fR
|
|
requirement in Method 2). One should never do this
|
|
(i.e. allow the Unix passwords to be sniffed on the
|
|
network).
|
|
.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] can 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 means 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 any value of options
|
|
associated with it does apply as normal.
|
|
.IP
|
|
There are also some utilities for testing password
|
|
if [list] starts with the "%" character. See the
|
|
quick_pw() function in the source for details.
|
|
.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 for any most modern
|
|
environments unless x11vnc is run as root to be able
|
|
to access /etc/shadow (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 you can run x11vnc
|
|
as root and use \fB-unixpw_nis.\fR Any users with passwords
|
|
in /etc/shadow can then be authenticated. You may want
|
|
to use \fB-users\fR unixpw= to switch the process user after
|
|
the user logs in.
|
|
.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 the username and the second line
|
|
the received password. If the command exits with status
|
|
0 (success) the VNC client will be accepted. It will be
|
|
rejected for any other return status.
|
|
.IP
|
|
Dynamic passwords and non-unix passwords can be
|
|
implemented this way by providing your own custom helper
|
|
program. Note that under unixpw mode the remote viewer
|
|
is given 3 tries to enter the correct password.
|
|
.IP
|
|
If a list of allowed users is needed use \fB-unixpw\fR [list]
|
|
in addition to this option.
|
|
.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
|
|
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).
|
|
.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
|
|
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-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".
|
|
.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-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
|
|
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.
|
|
.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.
|
|
.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 persistant 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 (e.g. "xauth extract -
|
|
$DISPLAY" output).
|
|
.IP
|
|
In the case of \fB-unixpw\fR (but not \fB-unixpw_nis),\fR then the
|
|
above command is run as the user who just authenticated
|
|
via the login and password prompt.
|
|
.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),
|
|
repeat, speeds= (or sp=), readtimeout= (or rd=),
|
|
rotate= (or ro=), or noncache (or nc) 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
|
|
Another option is "geom=WxH" or "geom=WxHxD" (or
|
|
ge=). This only has an effect in FINDCREATEDISPLAY
|
|
mode when a virtual X server such as Xvfb is going
|
|
to be created. It sets the width and height of
|
|
the new display, and optionally the color depth as
|
|
well. You can also supply "gnome", "kde", "twm",
|
|
"fvwm", "mwm", "dtwm", "wmaker", "xfce",
|
|
"enlightenment", "Xsession", or "failsafe"
|
|
(same as "xterm") to have the created display use
|
|
that mode for the user session.
|
|
.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
|
|
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
|
|
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
|
|
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
|
|
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. This can also be set by the
|
|
user via "nd=" using "-" instead of ","
|
|
.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
|
|
It will start looking for an open display number at :20
|
|
Override via X11VNC_CREATE_STARTING_DISPLAY_NUMBER=n
|
|
.IP
|
|
By default FINDCREATEDISPLAY will try Xdummy and then
|
|
Xvfb:
|
|
.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 requires root permission and only works
|
|
on Linux. (Note: specify FD_XDUMMY_NOROOT=1 to skip
|
|
a check for the root id; evidently your
|
|
.IR sudo (1)
|
|
will
|
|
take care of everything. The \fB-xdummy\fR and \fB-svc_xdummy\fR
|
|
options imply FD_XDUMMY_NOROOT=1).
|
|
.IP
|
|
Xvfb is available on most platforms and does not
|
|
require root.
|
|
.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
|
|
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
|
|
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 ...)
|
|
.IP
|
|
Use WAIT:cmd=FINDCREATEDISPLAY-print to print out the
|
|
script used.
|
|
.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 as 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. FD_XDUMMY_NOROOT means the Xdummy server
|
|
does not need to be started as root (e.g. it will sudo
|
|
automatically)
|
|
.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. This 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. This 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.
|
|
.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-ssl-tunnel-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 defaut "SAVE" method.
|
|
.IP
|
|
See \fB-ssldir\fR below to use a directory besides the
|
|
default ~/.vnc/certs
|
|
.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 \fI[dir]\fR
|
|
.IP
|
|
Use [dir] 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 \fI[path]\fR
|
|
.IP
|
|
For either of the \fB-ssl\fR or \fB-stunnel\fR modes, use [path]
|
|
to provide certificates to authenticate incoming VNC
|
|
*Client* connections (normally only the server is
|
|
authenticated in SSL.) This can be used as a method
|
|
to replace standard password authentication of clients.
|
|
.IP
|
|
If [path] is a directory it contains the client (or CA)
|
|
certificates in separate files. If [path] is a file,
|
|
it contains one or more certificates. See special tokens
|
|
below. These correspond to the "CApath = dir" and
|
|
"CAfile = file" stunnel options. See the
|
|
.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 [path] 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 and \fB-sslCertInfo\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.
|
|
.IP
|
|
If path is a file, the file contains one more 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
|
|
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].
|
|
.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
|
|
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 the command 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. 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 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 always
|
|
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 suppled 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 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 \fI[pem]\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 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 \fI[pem]\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
|
|
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 \fI[pem]\fR
|
|
.IP
|
|
Prompts you to delete all .crt .pem .key .req files
|
|
associated with [pem]. "SAVE" and lookups as in
|
|
\fB-sslCertInfo\fR apply as well.
|
|
.PP
|
|
\fB-stunnel\fR \fI[pem]\fR
|
|
.IP
|
|
Use the
|
|
.IR stunnel (8)
|
|
(www.stunnel.org) 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. This 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.
|
|
Whether one is needed or not depends on your stunnel
|
|
configuration. stunnel often generates one at install
|
|
time. See the stunnel documentation for details.
|
|
.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.
|
|
Set STUNNEL_DISABLE_LOCALHOST=1 before starting x11vnc
|
|
to disable the requirement.
|
|
.IP
|
|
Your VNC viewer will also need to be able to connect via
|
|
SSL. Unfortunately not too many do this. UltraVNC has
|
|
an encryption plugin but it does not seem to be SSL.
|
|
.IP
|
|
Also, in the x11vnc distribution, a patched TightVNC
|
|
Java applet is provided in classes/ssl that does SSL
|
|
connections (only).
|
|
.IP
|
|
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
|
|
.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 mode 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
|
|
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.
|
|
.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.
|
|
.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
|
|
only listen 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.
|
|
.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,
|
|
and classic X (i.e. with the background image on the
|
|
root window). The "gconftool-2" and "dcop" external
|
|
commands are run for GNOME and KDE respectively.
|
|
Other desktops won't work, e.g. Xfce (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 and KDE. If x11vnc guesses
|
|
your desktop incorrectly, you can force it by prefixing
|
|
color with "gnome:", "kde:", "cde:" or "root:".
|
|
.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.)
|
|
.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.
|
|
.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
|
|
.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 it this mode: they are mapped to
|
|
regular digit keysyms. See also \fB-capslock\fR above.
|
|
.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).
|
|
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
|
|
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
|
|
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.
|
|
.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-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.
|
|
.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. Default: XXX.
|
|
.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 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
|
|
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
|
|
.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 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-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 wait for updates before sending to client
|
|
(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-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: 20
|
|
.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: 60 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
|
|
Default: \fB-nothreads.\fR NOTE: The \fB-threads\fR mode is now
|
|
disabled due to its unstable behavior. Not recommended,
|
|
but you can recompile with \fB-DX11VNC_THREADED\fR in
|
|
CPPFLAGS if you need to use it. You can also set the
|
|
env. variable X11VNC_THREADED=1
|
|
.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. 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.
|
|
.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 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.
|
|
.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 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".
|
|
.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
|
|
You can also 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-gui\fR \fI[gui-opts]\fR
|
|
.IP
|
|
Start up a simple tcl/tk gui based on the 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.
|
|
.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 ...'
|
|
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
|
|
.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:<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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
defer:n set \fB-defer\fR to n ms,same as deferupdate:n
|
|
.IP
|
|
wait:n set \fB-wait\fR to n ms.
|
|
.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_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-macnmenu\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
|
|
The
|
|
.IR vncconnect (1)
|
|
command from standard VNC
|
|
.IP
|
|
distributions may also be used if string is prefixed
|
|
.IP
|
|
with "cmd=" E.g. 'vncconnect cmd=stop'. Under some
|
|
.IP
|
|
circumstances
|
|
.IR xprop (1)
|
|
can used if it supports \fB-set\fR
|
|
.IP
|
|
(see the FAQ).
|
|
.IP
|
|
.IP
|
|
If "\fB-connect\fR \fI/path/to/file\fR" has been supplied to the
|
|
.IP
|
|
running x11vnc server then that file can be used as a
|
|
.IP
|
|
communication channel (this is the only way to remote
|
|
.IP
|
|
control one of many x11vnc's polling the same X display)
|
|
.IP
|
|
Simply run: 'x11vnc \fB-connect\fR /path/to/file \fB-remote\fR ...'
|
|
.IP
|
|
or you can directly write to the file via something
|
|
.IP
|
|
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 blacken zero
|
|
refresh reset close disconnect 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 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 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 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 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 deferupdate defer setdefer 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 desktopname guess_desktop
|
|
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 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 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 so
|
|
if the x11vnc takes longer than that to process the
|
|
requests the requester will think that a failure has
|
|
taken place.
|
|
.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,
|
|
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 'storepasswd' 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).
|