$ x11vnc --help
x11vnc: allow VNC connections to real X11 displays. 0.9.10 lastmod: 2010-04-28
(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.
(snip)
-viewonly All VNC clients can only watch (default off).
-shared VNC display is shared, i.e. more than one viewer can
connect at the same time (default off).
-once Exit after the first successfully connected viewer
disconnects, opposite of -forever. This is the Default.
-forever Keep listening for more connections rather than exiting
as soon as the first client(s) disconnect. Same as -many
-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
(snip)
-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.
(snip)
-allow host1[,host2..] Only allow client connections from hosts matching
the comma separated list of hostnames or IP addresses.
Can also be a numerical IP prefix, e.g. "192.168.100."
to match a simple subnet, for more control build
LibVNCServer with libwrap support (See the FAQ). If the
list contains a "/" it instead is a interpreted
as a file containing addresses or prefixes that is
re-read each time a new client connects. Lines can be
commented out with the "#" character in the usual way.
-allow applies in -ssl mode, but not in -stunnel mode.
IPv6: as of x11vnc 0.9.10 a host can be specified
in IPv6 numerical format, e.g. 2001:4860:b009::93.
-localhost Basically the same as "-allow 127.0.0.1".
Note: if you want to restrict which network interface
x11vnc listens on, see the -listen option below.
E.g. "-listen localhost" or "-listen 192.168.3.21".
As a special case, the option "-localhost" implies
"-listen localhost".
A rare case, but for non-localhost -listen usage, if
you use the remote control mechanism (-R) to change
the -listen interface you may need to manually adjust
the -allow list (and vice versa) to avoid situations
where no connections (or too many) are allowed.
If you do not want x11vnc to listen on ANY interface
(evidently you are using -connect or -connect_or_exit,
or plan to use remote control: -R connect:host), use
-rfbport 0
IPv6: if IPv6 is supported, this option automatically
implies the IPv6 loopback address '::1' as well.
(snip)
-passwdfile filename Specify the LibVNCServer password via the first line
of the file "filename" (instead of via -passwd on
the command line where others might see it via ps(1)).
See the descriptions below for how to supply multiple
passwords, view-only passwords, to specify external
programs for the authentication, and other features.
If the filename is prefixed with "rm:" it will be
removed after being read. Perhaps this is useful in
limiting the readability of the file. In general, the
password file should not be readable by untrusted users
(BTW: neither should the VNC -rfbauth file: it is NOT
encrypted, only obscured with a fixed key).
If the filename is prefixed with "read:" it will
periodically be checked for changes and reread. It is
guaranteed to be reread just when a new client connects
so that the latest passwords will be used.
If "filename" is prefixed with "cmd:" then the
string after the ":" is run as an external command:
the output of the command will be interpreted as if it
were read from a password file (see below). If the
command does not exit with 0, then x11vnc terminates
immediately. To specify more than 1000 passwords this
way set X11VNC_MAX_PASSWDS before starting x11vnc.
The environment variables are set as in -accept.
Note that due to the VNC protocol only the first 8
characters of a password are used (DES key).
If "filename" is prefixed with "custom:" then a
custom password checker is supplied as an external
command following the ":". The command will be run
when a client authenticates. If the command exits with
0 the client is accepted, otherwise it is rejected.
The environment variables are set as in -accept.
The standard input to the custom command will be a
decimal digit "len" followed by a newline. "len"
specifies the challenge size and is usually 16 (the
VNC spec). Then follows len bytes which is the random
challenge string that was sent to the client. This is
then followed by len more bytes holding the client's
response (i.e. the challenge string encrypted via DES
with the user password in the standard situation).
The "custom:" scheme can be useful to implement
dynamic passwords or to implement methods where longer
passwords and/or different encryption algorithms
are used. The latter will require customizing the VNC
client as well. One could create an MD5SUM based scheme
for example.
File format for -passwdfile:
If multiple non-blank lines exist in the file they are
all taken as valid passwords. Blank lines are ignored.
Password lines may be "commented out" (ignored) if
they begin with the character "#" or the line contains
the string "__SKIP__". Lines may be annotated by use
of the "__COMM__" string: from it to the end of the
line is ignored. An empty password may be specified
via the "__EMPTY__" string on a line by itself (note
your viewer might not accept empty passwords).
If the string "__BEGIN_VIEWONLY__" appears on a
line by itself, the remaining passwords are used for
viewonly access. For compatibility, as a special case
if the file contains only two password lines the 2nd
one is automatically taken as the viewonly password.
Otherwise the "__BEGIN_VIEWONLY__" token must be
used to have viewonly passwords. (tip: make the 3rd
and last line be "__BEGIN_VIEWONLY__" to have 2
full-access passwords)
(snip)
-unixpw [list] Use Unix username and password authentication. x11vnc
will use the su(1) program to verify the user's
password. [list] is an optional comma separated list
of allowed Unix usernames. If the [list] string begins
with the character "!" then the entire list is taken
as an exclude list. See below for per-user options
that can be applied.
A familiar "login:" and "Password:" dialog is
presented to the user on a black screen inside the
vncviewer. The connection is dropped if the user fails
to supply the correct password in 3 tries or does not
send one before a 45 second timeout. Existing clients
are view-only during this period.
If the first character received is "Escape" then the
unix username will not be displayed after "login:"
as it is typed. This could be of use for VNC viewers
that automatically type the username and password.
Since the detailed behavior of su(1) can vary from
OS to OS and for local configurations, test the mode
before deployment to make sure it is working properly.
x11vnc will attempt to be conservative and reject a
login if anything abnormal occurs.
One case to note: FreeBSD and the other BSD's by
default it is impossible for the user running x11vnc to
validate his *own* password via su(1) (commenting out
the pam_self.so entry in /etc/pam.d/su eliminates this
behavior). So the x11vnc login will always *FAIL* for
this case (even when the correct password is supplied).
A possible workaround for this on *BSD would be to
start x11vnc as root with the "-users +nobody" option
to immediately switch to user nobody where the su'ing
will proceed normally.
Another source of potential problems are PAM modules
that prompt for extra info, e.g. password aging modules.
These logins will fail as well even when the correct
password is supplied.
**IMPORTANT**: to prevent the Unix password being sent
in *clear text* over the network, one of two schemes
will be enforced: 1) the -ssl builtin SSL mode, or 2)
require both -localhost and -stunnel be enabled.
Method 1) ensures the traffic is encrypted between
viewer and server. A PEM file will be required, see the
discussion under -ssl below (under some circumstances
a temporary one can be automatically generated).
Method 2) requires the viewer connection to appear
to come from the same machine x11vnc is running on
(e.g. from a ssh -L port redirection). And that the
-stunnel SSL mode be used for encryption over the
network. (see the description of -stunnel below).
Note: as a convenience, if you ssh(1) in and start
x11vnc it will check if the environment variable
SSH_CONNECTION is set and appears reasonable. If it
does, then the -ssl or -stunnel requirement will be
dropped since it is assumed you are using ssh for the
encrypted tunnelling. -localhost is still enforced.
Use -ssl or -stunnel to force SSL usage even if
SSH_CONNECTION is set.
To override the above restrictions you can set
environment variables before starting x11vnc:
Set UNIXPW_DISABLE_SSL=1 to disable requiring either
-ssl or -stunnel (as under SSH_CONNECTION.) Evidently
you will be using a different method to encrypt the
data between the vncviewer and x11vnc: perhaps ssh(1)
or an IPSEC VPN. -localhost is still enforced (however,
see the next paragraph.)
Set UNIXPW_DISABLE_LOCALHOST=1 to disable the -localhost
requirement in -unixpw modes. One should never do this
(i.e. allow the Unix passwords to be sniffed on the
network.) This also disables the localhost requirement
for reverse connections (see below.)
Note that use of -localhost with ssh(1) (and no -unixpw)
is roughly the same as requiring a Unix user login
(since a Unix password or the user's public key
authentication is used by sshd on the machine where
x11vnc runs and only local connections from that machine
are accepted).
Regarding reverse connections (e.g. -R connect:host
and -connect host), when the -localhost constraint is
in effect then reverse connections can only be used
to connect to the same machine x11vnc is running on
(default port 5500). Please use a ssh or stunnel port
redirection to the viewer machine to tunnel the reverse
connection over an encrypted channel.
In -inetd mode the Method 1) will be enforced (not
Method 2). With -ssl in effect reverse connections
are disabled. If you override this via env. var, be
sure to also use encryption from the viewer to inetd.
Tip: you can also have your own stunnel spawn x11vnc
in -inetd mode (thereby bypassing inetd). See the FAQ
for details.
The user names in the comma separated [list] may have
per-user options after a ":", e.g. "fred:opts"
where "opts" is a "+" separated list of
"viewonly", "fullaccess", "input=XXXX", or
"deny", e.g. "karl,wally:viewonly,boss:input=M".
For "input=" it is the K,M,B,C described under -input.
If an item in the list is "*" that means those
options apply to all users. It ALSO implies all users
are allowed to log in after supplying a valid password.
Use "deny" to explicitly deny some users if you use
"*" to set a global option. If [list] begins with the
"!" character then "*" is ignored for checking if
the user is allowed, but the option values associated
with it do apply as normal.
There are also some utilities for checking passwords
if [list] starts with the "%" character. See the
quick_pw() function for more details. Description:
"%-" or "%stdin" means read one line from stdin.
"%env" means it is in $UNIXPW env var. A leading
"%/" or "%." means read the first line from the
filename that follows after the % character. % by
itself means prompt for the username and password.
Otherwise: %user:pass E.g. -unixpw %fred:swordfish
For the other cases user:pass is read from the indicated
source. If the password is correct 'Y user' is printed
and the program exit code is 0. If the password is
incorrect it prints 'N user' and the exit code is 1.
If there is some other error the exit code is 2.
This feature enables x11vnc to be a general unix user
password checking tool; it could be used from scripts
or other programs. These % password checks also apply
to the -unixpw_nis and -unixpw_cmd options.
For the % password check, if the env. var. UNIXPW_CMD
is set to a command then it is run as the user (assuming
the password is correct.) The output of the command is
not printed, the program or script must manage that by
some other means. The exit code of x11vnc will depend
on the exit code of the command that is run.
Use -nounixpw to disable unixpw mode if it was enabled
earlier in the cmd line (e.g. -svc mode)
(snip)
-storepasswd pass file Store password "pass" as the VNC password in the
file "file". Once the password is stored the
program exits. Use the password via "-rfbauth file"
If called with no arguments, "x11vnc -storepasswd",
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.
-nopw Disable the big warning message when you use x11vnc
without some sort of password.
(snip)
-users list If x11vnc is started as root (say from inetd(8) or from
display managers xdm(1), 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 "list". If x11vnc is not running as
root this option is ignored.
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 "-solid color" 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 -accept and
-gone options. It also affects the ability to read
files for options such as -connect, -allow, and -remap
and also the ultra and tight filetransfer feature if
enabled. Note that the -connect file is also sometimes
written to.
So be careful with this option since in some situations
its use can decrease security.
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: "-users fred,wilma,betty".
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?
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. "-users +bob" or "-users +nobody".
The latter (i.e. switching immediately to user
"nobody") is the only obvious use of the -users option
that increases security.
Use the following notation to associate a group with
a user: user1.group1,user2.group2,... Note that
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
setgid(2). Use -env X11VNC_SINGLE_GROUP=1 to prevent
trying 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.
In -unixpw mode, if "-users unixpw=" is supplied
then after a user authenticates himself via the
-unixpw mechanism, x11vnc will try to switch to that
user as though "-users +username" 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.
Similarly, in -ssl mode, if "-users sslpeer=" is
supplied then after an SSL client authenticates with his
cert (the -sslverify 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 "-users +username" 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.
NOTE: for sslpeer= mode the x11vnc administrator must
take care that any client certs he adds to -sslverify
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 -text -in file.crt", see the
"Subject:" line. Also, along with the normal RFB_*
env. vars. (see -accept) passed to external cmd=
commands, RFB_SSL_CLIENT_CERT will be set to the
client's x509 certificate string.
The sslpeer= mode can aid finding X sessions via the
FINDDISPLAY and FINDCREATEDISPLAY mechanisms.
To immediately switch to a user *before* connections
to the X display are made or any files opened use the
"=" character: "-users =bob". That user needs to
be able to open the X display and any files of course.
The special user "guess=" means to examine the utmpx
database (see who(1)) looking for a user attached to
the display number (from DISPLAY or -display option)
and try him/her. To limit the list of guesses, use:
"-users guess=bob,betty".
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 "-display WAIT:..." functionality. Examples:
"-users lurk=" and also "-users lurk=:0-1,bob,mary"
Be especially careful using the "guess=" and "lurk="
modes. They are not recommended for use on machines
with untrustworthy local users.
(snip)
-ping n Send a 1x1 framebuffer update to all clients every n
seconds (e.g. to try to keep a network connection alive)
(snip)
These options are passed to LibVNCServer:
-rfbport port TCP port for RFB protocol
-rfbwait time max time in ms to wait for RFB client
-rfbauth passwd-file use authentication on RFB protocol
(use 'storepasswd' to create a password file)
-rfbversion 3.x Set the version of the RFB we choose to advertise
-permitfiletransfer permit file transfer support
-passwd plain-password use authentication
(use plain-password as password, USE AT YOUR RISK)
-deferupdate time time in ms to defer updates (default 40)
-deferptrupdate time time in ms to defer pointer updates (default none)
-desktop name VNC desktop name (default "LibVNCServer")
-alwaysshared always treat new clients as shared
-nevershared never treat new clients as shared
-dontdisconnect don't disconnect existing clients when a new non-shared
connection comes in (refuse new connection instead)
-httpdir dir-path enable http server using dir-path home
-httpport portnum use portnum for http connection
-enablehttpproxy enable http proxy support
-progressive height enable progressive updating for slow links
-listen ipaddr listen for connections only on network interface with
addr ipaddr. '-listen localhost' and hostname work too.
libvncserver-tight-extension options:
-disablefiletransfer disable file transfer
-ftproot string set ftp root
