Professional Documents
Culture Documents
13 lastmod: 2011-08-10
(type "x11vnc -opts" to just list the options.)
Typical usage is:
Run this command in a shell on the remote machine "far-host"
with X session you wish to view:
x11vnc -display :0
Then run this in another window on the machine you are sitting at:
vncviewer far-host:0
Once x11vnc establishes connections with the X11 server and starts listening
as a VNC server it will print out a string: PORT=XXXX where XXXX is typically
5900 (the default VNC server port). One would next run something like
this on the local machine: "vncviewer hostname:N" where "hostname" is
the name of the machine running x11vnc and N is XXXX - 5900, i.e. usually
"vncviewer hostname:0".
By default x11vnc will not allow the screen to be shared and it will exit
as soon as the client disconnects. See -shared and -forever below to override
these protections. See the FAQ for details how to tunnel the VNC connection
through an encrypted channel such as ssh(1). In brief:
ssh -t -L 5900:localhost:5900 far-host 'x11vnc -localhost -display :0'
vncviewer -encodings 'copyrect tight zrle hextile' localhost:0
Also, use of a VNC password (-rfbauth or -passwdfile) is strongly recommended.
For additional info see: http://www.karlrunge.com/x11vnc/
and http://www.karlrunge.com/x11vnc/faq.html
Config file support: if the file $HOME/.x11vncrc exists then each line in
it is treated as a single command line option. Disable with -norc. For
each option name, the leading character "-" is not required. E.g. a line
that is either "forever" or "-forever" may be used and are equivalent.
Likewise "wait 100" or "-wait 100" are acceptable and equivalent lines.
The "#" character comments out to the end of the line in the usual way
(backslash it for a literal). Leading and trailing whitespace is trimmed off.
Lines may be continued with a "\" as the last character of a line (it
becomes a space character).
Options:
-display disp X11 server display to connect to, usually :0. The X
server process must be running on same machine and
support MIT-SHM. Equivalent to setting the DISPLAY
environment variable to "disp".
See the description below of the "-display WAIT:..."
extensions, where alias "-find" will find the user's
display automatically, and "-create" will create a
Xvfb session if no session is found.
-auth file Set the X authority file to be "file", equivalent to
setting the XAUTHORITY environment variable to "file"
before startup. Same as -xauth file. See Xsecurity(7),
xauth(1) man pages for more info.
Use '-auth guess' to have x11vnc use its -findauth
mechanism (described below) to try to guess the
XAUTHORITY filename and use it.
XDM/GDM/KDM: if you are running x11vnc as root and want
to find the XAUTHORITY before anyone has logged into an
X session yet, use: x11vnc -env FD_XDM=1 -auth guess ...
(This will also find the XAUTHORITY if a user is already
logged into the X session.) When running as root,
FD_XDM=1 will be tried if the initial -auth guess fails.
-N If the X display is :N, try to set the VNC display to
also be :N This just sets the -rfbport option to 5900+N
The program will exit immediately if that port is not
available. The -N option only works with normal -display
usage, e.g. :0 or :8, -N is ignored in the -display
WAIT:..., -create, -find, -svc, -redirect, etc modes.
-autoport n Automatically probe for a free VNC port starting at n.
The default is to start probing at 5900. Use this to
stay away from other VNC servers near 5900.
-rfbport str The VNC port to listen on (a LibVNCServer option), e.g.
5900, 5901, etc. If specified as "-rfbport PROMPT"
then the x11vnc -gui is used to prompt the user to
enter the port number.
-6 IPv6 listening support. In addition to IPv4, the
IPv6 address is listened on for incoming connections.
The same port number as IPv4 is used.
NOTE: This x11vnc binary was compiled to have the
"-6" IPv6 listening mode ENABLED by default (CPPFLAGS
-DX11VNC_LISTEN6=1). So to disable IPv6 listening mode
you MUST supply the "-no6" option (see below.)
The "-6" mode works for both normal connections and
-ssl encrypted ones. Nearly everything is supported
for the IPv6 case, but there are a few exceptions.
See -stunnel for its IPv6 support.
Currently, for absolutely everything to work correctly
the machine may need to have some IPv4 support, at the
least for the loopback interface. However, for nearly
all usage modes no IPv4 support is required. See -nopiv4.
If you have trouble compiling or running in IPv6 mode,
set -DX11VNC_IPV6=0 in CPPFLAGS when configuring to
disable IPv6 support.
-no6 Disable IPv6 listening support (only useful if the
"-6" mode is compiled in to be the default; see the
X11VNC_LISTEN6 description above under "-6".)
-noipv6 Do not try to use IPv6 for any listening or connecting
sockets. This includes both the listening service
port(s) and outgoing connections from -connect,
-connect_or_exit, or -proxy. Use this if you are having
problems due to IPv6.
-noipv4 Do not try to use IPv4 for any listening or connecting
sockets. This is mainly for exploring the behavior of
x11vnc on an IPv6-only system, but may have other uses.
-reopen If the X server connection is disconnected, try to
reopen the X display (up to one time.) This is of use
for display managers like GDM (KillInitClients option)
that kill x11vnc just after the user logs into the
X session. Note: the reopened state may be unstable.
Set X11VNC_REOPEN_DISPLAY=n to reopen n times and
set X11VNC_REOPEN_SLEEP_MAX to the number of seconds,
default 10, to keep trying to reopen the display (once
per second.)
Update: as of 0.9.9, x11vnc tries to automatically avoid
being killed by the display manager by delaying creating
windows or using XFIXES. So you shouldn't need to use
KillInitClients=false as long as you log in quickly
enough (within 45 seconds of connecting.) You can
disable this by setting X11VNC_AVOID_WINDOWS=never.
You can also set it to the number of seconds to delay.
-reflect host:N Instead of connecting to and polling an X display,
connect to the remote VNC server host:N and be a
reflector/repeater for it. This is useful for trying
to manage the case of many simultaneous VNC viewers
(e.g. classroom broadcasting) where, e.g. you put
a repeater on each network switch, etc, to improve
performance by distributing the load and network
traffic. Implies -shared (use -noshared as a later
option to disable). See the discussion below under
-rawfb vnc:host:N for more details.
-id windowid Show the X window corresponding to "windowid" not
the entire display. New windows like popup menus,
transient toplevels, etc, may not be seen or may be
clipped. Disabling SaveUnders or BackingStore in the
X server may help show them. x11vnc may crash if the
window is initially partially obscured, changes size,
is iconified, etc. Some steps are taken to avoid this
and the -xrandr mechanism is used to track resizes. Use
xwininfo(1) to get the window id, or use "-id pick"
to have x11vnc run xwininfo(1) for you and extract
the id. The -id option is useful for exporting very
simple applications (e.g. the current view on a webcam).
-sid windowid As -id, but instead of using the window directly it
shifts a root view to it: this shows SaveUnders menus,
etc, although they will be clipped if they extend beyond
the window.
-tag str This option is ignored, but allows you to specify a
unique string on the x11vnc command line, for example
"-tag test34934z", this could enable a reliable
way to identify different x11vnc processes via their
command lines (see ps(1), pgrep(1), and pkill(1)
and /proc/PID/cmdline.)
-appshare Simple application sharing based on the -id/-sid
mechanism. Every new toplevel window that the
application creates induces a new viewer window via
a reverse connection. The -id/-sid and -connect
options are required. Run 'x11vnc -appshare -help'
for more info.
-clip WxH+X+Y Only show the sub-region of the full display that
corresponds to the rectangle geometry with size WxH and
offset +X+Y. The VNC display has size WxH (i.e. smaller
than the full display). This also works for -id/-sid
mode where the offset is relative to the upper left
corner of the selected window. An example use of this
option would be to split a large (e.g. Xinerama) display
into two parts to be accessed via separate viewers by
running a separate x11vnc on each part.
Use '-clip xinerama0' to clip to the first xinerama
sub-screen (if xinerama is active). xinerama1 for the
2nd sub-screen, etc. This way you don't need to figure
out the WxH+X+Y of the desired xinerama sub-screen.
screens are sorted in increasing distance from the
(0,0) origin (I.e. not the Xserver's order).
-flashcmap In 8bpp indexed color, let the installed colormap flash
as the pointer moves from window to window (slow).
Also try the -8to24 option to avoid flash altogether.
-shiftcmap n Rare problem, but some 8bpp displays use less than 256
colorcells (e.g. 16-color grayscale, perhaps the other
bits are used for double buffering) *and* also need to
shift the pixels values away from 0, .., ncells. "n"
indicates the shift to be applied to the pixel values.
To see the pixel values set DEBUG_CMAP=1 to print out
a colormap histogram. Example: -shiftcmap 240
-notruecolor For 8bpp displays, force indexed color (i.e. a colormap)
even if it looks like 8bpp TrueColor (rare problem).
-advertise_truecolor If the X11 display is indexed color, lie to clients
when they first connect by telling them it is truecolor.
To workaround RealVNC: inPF has colourMap but not 8bpp
Use '-advertise_truecolor reset' to reset client fb too.
-visual n This option probably does not do what you think.
It simply *forces* the visual used for the framebuffer;
this may be a bad thing... (e.g. messes up colors or
cause a crash). It is useful for testing and for some
workarounds. n may be a decimal number, or 0x hex.
Run xdpyinfo(1) for the values. One may also use
"TrueColor", etc. see <X11/X.h> for a list. If the
string ends in ":m" then for better or for worse
the visual depth is forced to be m. You may want to
use -noshm when using this option (so XGetImage may
automatically translate the pixel data).
-overlay Handle multiple depth visuals on one screen, e.g. 8+24
and 24+8 overlay visuals (the 32 bits per pixel are
packed with 8 for PseudoColor and 24 for TrueColor).
Currently -overlay only works on Solaris via
XReadScreen(3X11) and IRIX using XReadDisplay(3).
On Solaris there is a problem with image "bleeding"
around transient popup menus (but not for the menu
itself): a workaround is to disable SaveUnders
by passing the "-su" argument to Xsun (in
/etc/dt/config/Xservers).
Use -overlay as a workaround for situations like these:
Some legacy applications require the default visual to
be 8bpp (8+24), or they will use 8bpp PseudoColor even
when the default visual is depth 24 TrueColor (24+8).
In these cases colors in some windows will be incorrect
in x11vnc unless -overlay is used. Another use of
-overlay is to enable showing the exact mouse cursor
shape (details below).
Under -overlay, performance will be somewhat slower
due to the extra image transformations required.
For optimal performance do not use -overlay, but rather
configure the X server so that the default visual is
depth 24 TrueColor and try to have all apps use that
visual (e.g. some apps have -use24 or -visual options).
-overlay_nocursor Sets -overlay, but does not try to draw the exact mouse
cursor shape using the overlay mechanism.
-8to24 [opts] Try this option if -overlay is not supported on your
OS, and you have a legacy 8bpp app that you want to
view on a multi-depth display with default depth 24
(and is 32 bpp) OR have a default depth 8 display with
depth 24 overlay windows for some apps. This option
may not work on all X servers and hardware (tested
on XFree86/Xorg mga driver and Xsun). The "opts"
string is not required and is described below.
This mode enables a hack where x11vnc monitors windows
within 3 levels from the root window. If it finds
any that are 8bpp it extracts the indexed color
pixel values using XGetImage() and then applies a
transformation using the colormap(s) to create TrueColor
RGB values that it in turn inserts into bits 1-24 of
the framebuffer. This creates a depth 24 "view"
of the display that is then exported via VNC.
Conversely, for default depth 8 displays, the depth
24 regions are read by XGetImage() and everything is
transformed and inserted into a depth 24 TrueColor
framebuffer.
Note that even if there are *no* depth 24 visuals or
windows (i.e. pure 8bpp), this mode is potentially
an improvement over -flashcmap because it avoids the
flashing and shows each window in the correct color.
This method works OK, but may still have bugs and it
does hog resources. If there are multiple 8bpp windows
using different colormaps, one may have to iconify all
but one for the colors to be correct.
There may be painting errors for clipping and switching
between windows of depths 8 and 24. Heuristics are
applied to try to minimize the painting errors. One can
also press 3 Alt_L's in a row to refresh the screen
if the error does not repair itself. Also the option
-fixscreen 8=3.0 or -fixscreen V=3.0 may be used to
periodically refresh the screen at the cost of bandwidth
(every 3 sec for this example).
The [opts] string can contain the following settings.
Multiple settings are separated by commas.
For for some X servers with default depth 24 a
speedup may be achieved via the option "nogetimage".
This enables a scheme were XGetImage() is not used
to retrieve the 8bpp data. Instead, it assumes that
the 8bpp data is in bits 25-32 of the 32bit X pixels.
There is no requirement that the X server should put
the data there for our poll requests, but some do and
so the extra steps to retrieve it can be skipped.
Tested with mga driver with XFree86/Xorg. For the
default depth 8 case this option is ignored.
To adjust how often XGetImage() is used to poll the
non-default visual regions for changes, use the option
"poll=t" where "t" is a floating point time.
(default: 0.05)
Setting the option "level2" will limit the search
for non-default visual windows to two levels from the
root window. Do this on slow machines where you know
the window manager only imposes one extra window between
the app window and the root window.
Also for very slow machines use "cachewin=t"
where t is a floating point amount of time to cache
XGetWindowAttributes results. E.g. cachewin=5.0.
This may lead to the windows being unnoticed for this
amount of time when deiconifying, painting errors, etc.
While testing on a very old SS20 these options gave
tolerable response: -8to24 poll=0.2,cachewin=5.0. For
this machine -overlay is supported and gives better
response.
Debugging for this mode can be enabled by setting
"dbg=1", "dbg=2", or "dbg=3".
-24to32 Very rare problem: if the framebuffer (X display
or -rawfb) is 24bpp instead of the usual 32bpp, then
dynamically transform the pixels to 32bpp. This will be
slower, but can be used to work around problems where
VNC viewers cannot handle 24bpp (e.g. "main: setPF:
not 8, 16 or 32 bpp?"). See the FAQ for more info.
In the case of -rawfb mode, the pixels are directly
modified by inserting a 0 byte to pad them out to 32bpp.
For X displays, a kludge is done that is equivalent to
"-noshm -visual TrueColor:32". (If better performance
is needed for the latter, feel free to ask).
-scale fraction Scale the framebuffer by factor "fraction". Values
less than 1 shrink the fb, larger ones expand it. Note:
the image may not be sharp and response may be slower.
If "fraction" contains a decimal point "." it
is taken as a floating point number, alternatively
the notation "m/n" may be used to denote fractions
exactly, e.g. -scale 2/3
To scale asymmetrically in the horizontal and vertical
directions, specify a WxH geometry to stretch to:
e.g. '-scale 1024x768', or also '-scale 0.9x0.75'
Scaling Options: can be added after "fraction" via
":", to supply multiple ":" options use commas.
If you just want a quick, rough scaling without
blending, append ":nb" to "fraction" (e.g. -scale
1/3:nb). No blending is the default for 8bpp indexed
color, to force blending for this case use ":fb".
To disable -scrollcopyrect and -wirecopyrect under
-scale use ":nocr". If you need to to enable them use
":cr" or specify them explicitly on the command line.
If a slow link is detected, ":nocr" may be applied
automatically. Default: :cr
More esoteric options: for compatibility with vncviewers
the scaled width is adjusted to be a multiple of 4:
to disable this use ":n4". ":in" use interpolation
scheme even when shrinking, ":pad" pad scaled width
and height to be multiples of scaling denominator
(e.g. 3 for 2/3).
-geometry WxH Same as -scale WxH
-scale_cursor frac By default if -scale is supplied the cursor shape is
scaled by the same factor. Depending on your usage,
you may want to scale the cursor independently of the
screen or not at all. If you specify -scale_cursor
the cursor will be scaled by that factor. When using
-scale mode to keep the cursor at its "natural" size
use "-scale_cursor 1". Most of the ":" scaling
options apply here as well.
-viewonly All VNC clients can only watch (default off).
-shared VNC display is shared, i.e. more than one viewer can
connect at the same time (default on).
-once Exit after the first successfully connected viewer
disconnects, opposite of -forever. This is the Default.
-forever Keep listening for more connections rather than exiting
as soon as the first client(s) disconnect. Same as -many
To get the standard non-shared VNC behavior where when
a new VNC client connects the existing VNC client is
dropped use: -nevershared -forever This method can
also be used to guard against hung TCP connections that
do not go away.
-loop Create an outer loop restarting the x11vnc process
whenever it terminates. -bg and -inetd are ignored
in this mode (however see -loopbg below).
Useful for continuing even if the X server terminates
and restarts (at that moment the process will need
permission to reconnect to the new X server of course).
Use, e.g., -loop100 to sleep 100 millisecs between
restarts, etc. Default is 2000ms (i.e. 2 secs) Use,
e.g. -loop300,5 to sleep 300 ms and only loop 5 times.
If -loopbg (plus any numbers) is specified instead,
the "-bg" option is implied and the mode approximates
inetd(8) usage to some degree. In this case when
it goes into the background any listening sockets
(i.e. ports 5900, 5800) are closed, so the next one
in the loop can use them. This mode will only be of
use if a VNC client (the only client for that process)
is already connected before the process goes into the
background, for example, usage of -display WAIT:..,
-svc, and -connect can make use of this "poor man's"
inetd mode. The default wait time is 500ms in this
mode. This usage could use useful: -svc -bg -loopbg
-timeout n Exit unless a client connects within the first n seconds
after startup.
If there have been no connection attempts after n
seconds x11vnc exits immediately. If a client is
trying to connect but has not progressed to the normal
operating state, x11vnc gives it a few more seconds
to finish and exits if it does not make it to the
normal state.
For reverse connections via -connect or -connect_or_exit
a timeout of n seconds will be set for all reverse
connects. If the connect timeout alarm goes off,
x11vnc will exit immediately.
-sleepin n At startup sleep n seconds before proceeding (e.g. to
allow redirs and listening clients to start up)
If a range is given: '-sleepin min-max', a random value
between min and max is slept. E.g. '-sleepin 0-20' and
'-sleepin 10-30'. Floats are allowed too.
-inetd Launched by inetd(8): stdio instead of listening socket.
Note: if you are not redirecting stderr to a log file
(via shell 2> or -o option) you MUST also specify the -q
option, otherwise the stderr goes to the viewer which
will cause it to abort. Specifying both -inetd and -q
and no -o will automatically close the stderr.
If the libvncserver used supports non AF_INET sockets
(the one bundled in x11vnc 0.9.13 and later does),
then -inetd mode can be used for a raw stdio pipe. For
example, using the SSVNC viewer exec=... mechanism:
ssvnc -viewer exec="ssh -tt -e none user@host \
'x11vnc -inetd -o log.txt -display :0'"
where the long cmdline has been split. In the above
the only TCP connection is that of the ssh connection.
There is no port redirection (-L), etc.; raw stdio is
used on both sides of the ssh. In some cases the -tt
option is not needed.
-tightfilexfer Enable the TightVNC file transfer extension. Note that
that when the -viewonly option is supplied all file
transfers are disabled. Also clients that log in
viewonly cannot transfer files. However, if the remote
control mechanism is used to change the global or
per-client viewonly state the filetransfer permissions
will NOT change.
IMPORTANT: please understand if -tightfilexfer is
specified and you run x11vnc as root for, say, inetd
or display manager (gdm, kdm, ...) access and you do
not have it switch users via the -users option, then
VNC Viewers that connect are able to do filetransfer
reads and writes as *root*.
Also, tightfilexfer is disabled in -unixpw mode.
-ultrafilexfer Note: to enable UltraVNC filetransfer and to get it to
work you probably need to supply these LibVNCServer
options: "-rfbversion 3.6 -permitfiletransfer"
"-ultrafilexfer" is an alias for this combination.
IMPORTANT: please understand if -ultrafilexfer is
specified and you run x11vnc as root for, say, inetd
or display manager (gdm, kdm, ...) access and you do
not have it switch users via the -users option, then
VNC Viewers that connect are able to do filetransfer
reads and writes as *root*.
Note that sadly you cannot do both -tightfilexfer and
-ultrafilexfer at the same time because the latter
requires setting the version to 3.6 and tightvnc will
not do filetransfer when it sees that version number.
-http Instead of using -httpdir (see below) to specify
where the Java vncviewer applet is, have x11vnc try
to *guess* where the directory is by looking relative
to the program location and in standard locations
(/usr/local/share/x11vnc/classes, etc). Under -ssl or
-stunnel the ssl classes subdirectory is sought.
-http_ssl As -http, but force lookup for ssl classes subdir.
Note that for HTTPS, single-port Java applet delivery
you can set X11VNC_HTTPS_DOWNLOAD_WAIT_TIME to the
max number of seconds to wait for the applet download
to finish. The default is 15.
-avahi Use the Avahi/mDNS ZeroConf protocol to advertise
this VNC server to the local network. (Related terms:
Rendezvous, Bonjour). Depending on your setup, you
may need to start avahi-daemon and open udp port 5353
in your firewall.
You can set X11VNC_AVAHI_NAME, X11VNC_AVAHI_HOST,
and/or X11VNC_AVAHI_PORT environment variables
to override the default values. For example:
-env X11VNC_AVAHI_NAME=wally
If the avahi API cannot be found at build time, a helper
program like avahi-publish(1) or dns-sd(1) will be tried
-mdns Same as -avahi.
-zeroconf Same as -avahi.
-connect string For use with "vncviewer -listen" reverse connections.
If "string" has the form "host" or "host:port"
the connection is made once at startup.
Use commas for a list of host's and host:port's.
E.g. -connect host1,host2 or host1:0,host2:5678.
Note that to reverse connect to multiple hosts at the
same time you will likely need to also supply: -shared
Note that unlike most vnc servers, x11vnc will require a
password for reverse as well as for forward connections.
(provided password auth has been enabled, -rfbauth, etc)
If you do not want to require a password for reverse
connections set X11VNC_REVERSE_CONNECTION_NO_AUTH=1 in
your environment before starting x11vnc.
If "string" contains "/" it is instead interpreted
as a file to periodically check for new hosts.
The first line is read and then the file is truncated.
Be careful about the location of this file if x11vnc
is running as root (e.g. via gdm(1), etc).