diff options
Diffstat (limited to 'x11vnc/x11vnc.1')
| -rw-r--r-- | x11vnc/x11vnc.1 | 839 |
1 files changed, 801 insertions, 38 deletions
diff --git a/x11vnc/x11vnc.1 b/x11vnc/x11vnc.1 index c8490bc..9dc9386 100644 --- a/x11vnc/x11vnc.1 +++ b/x11vnc/x11vnc.1 @@ -2,7 +2,7 @@ .TH X11VNC "1" "June 2006" "x11vnc " "User Commands" .SH NAME x11vnc - allow VNC connections to real X11 displays - version: 0.8.1, lastmod: 2006-06-03 + version: 0.8.2, lastmod: 2006-06-08 .SH SYNOPSIS .B x11vnc [OPTION]... @@ -60,7 +60,8 @@ becomes a space character). 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. +environment variable to \fIdisp\fR. See the description +below of the "\fB-display\fR \fIWAIT:...\fR" extensions. .PP \fB-auth\fR \fIfile\fR .IP @@ -355,7 +356,7 @@ after startup. \fB-inetd\fR .IP Launched by -.IR inetd (1): +.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 @@ -515,6 +516,755 @@ 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. 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 +Since the detailed behavior of +.IR su (1) +can vary from +OS to OS and for local configurations, test the mode +carefully on your systems before using it in production. +Test different combinations of valid/invalid usernames +and valid/invalid passwords to see if it behaves as +expected. x11vnc will attempt to be conservative and +reject a login if anything abnormal occurs. +.IP +On 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) +(evidently commenting out +the pam_self.so entry in /etc/pam.d/su eliminates this +problem). So the x11vnc login will always *fail* for +this case (even when the correct password is supplied). +.IP +A possible workaround for this would be to start +x11vnc as root with the "\fB-users\fR \fI+nobody\fR" option to +immediately switch to user nobody. Another source of +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. Note that in \fB-ssl\fR +mode reverse connection are disabled (see below). +.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,fred:viewonly,boss:input=M". +For "input=" it is the K,M,B,C described under \fB-input.\fR +.IP +If a user 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. +.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 instead. This requires that the +encrypted passwords be readable. 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 the user encrypted passwords are accessible +(e.g. "ypcat passwd"). 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 other modern environment. All of the \fB-unixpw\fR +options and contraints apply. +.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. 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>. 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 then the above command is run +as the user who just authenticated via the login and +password prompt. +.IP +Thus 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 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. this is TBD. +.IP +Finally, one can 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. +.PP +\fB-ssl\fR \fI[pem]\fR +.IP +Use the openssl library (www.openssl.org) to provide a +built-in encrypted SSL 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 +[pem] is optional, use "\fB-ssl\fR \fI/path/to/mycert.pem\fR" +to specify a PEM certificate file 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 option below. +.IP +The connecting VNC viewer SSL tunnel can optionally +authenticate this server if they have the public +key part of the certificate (or a common certificate +authority, CA, is a more sophisicated way to verify +this server's cert, see \fB-sslGenCA\fR below). This is +used to prevent man-in-the-middle attacks. Otherwise, +if the VNC viewer accepts this server's key without +verification, at least the traffic is protected +from passive sniffing on the network (but NOT from +man-in-the-middle attacks). +.IP +If [pem] is not supplied and the +.IR openssl (1) +utility +command exists in PATH, then a temporary, self-signed +certificate will be generated for this session (this +may take 5-30 seconds on slow machines). If +.IR openssl (1) +cannot be used to generate a temporary certificate +x11vnc exits immediately. +.IP +If successful in using +.IR openssl (1) +to generate a +temporary certificate, 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.) See following paragraphs for how to save +keys to reuse when x11vnc is restarted. +.IP +Set the env. var. X11VNC_SHOW_TMP_PEM=1 to have x11vnc +print out the entire certificate, including the PRIVATE +KEY part, to stderr. One could reuse this cert if saved +in a [pem] file. Similarly, set X11VNC_KEEP_TMP_PEM=1 +to not delete the temporary PEM file: the file name +will be printed to stderr (so one could move it to +a safe place for reuse). You will be prompted for a +passphrase for the private key. +.IP +If [pem] is "SAVE" then the certificate will be saved +to the file ~/.vnc/certs/server.pem, or if that file +exists it will be used directly. Similarly, if [pem] +is "SAVE_PROMPT" the server.pem certificate will be +made based on your answers to its prompts for 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. E.g. "SAVE-charlie" will store to the file +~/.vnc/certs/server-charlie.pem +.IP +See \fB-ssldir\fR below to use a directory besides the +default ~/.vnc/certs +.IP +Example: x11vnc \fB-ssl\fR SAVE \fB-display\fR :0 ... +.IP +Reverse connections are disabled in \fB-ssl\fR mode because +there is no way to ensure that data channel will +be encrypted. Set X11VNC_SSL_ALLOW_REVERSE=1 to +override this. +.IP +Your VNC viewer will also need to be able to connect +via SSL. See the discussion below under \fB-stunnel\fR and +the FAQ (ssl_vncviewer script) for how this might be +achieved. E.g. on Unix it is easy to write a shell +script that starts up stunnel and then vncviewer. +Also in the x11vnc source a SSL enabled Java VNC Viewer +applet is provided in the classes/ssl directory. +.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 multiple 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.pem +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 (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 +simplest mode can be improved by using "\fB-ssl\fR \fISAVE\fR" +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 ssl_vncviewer example script in the FAQ.) +.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 certicate 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-quailified 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 certicate. +.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 ssl_vncviewer stunnel wrapper +(see the FAQ): +ssl_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 +ssl_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 +ssl_vncviewer \fB-mycert\fR ./roger.pem hostname:0 +.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 +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-https\fR \fI[port]\fR +.IP +Choose a separate HTTPS port (-ssl mode only). +.IP +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 +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 it will try to guess +the directory as though the \fB-http\fR option was supplied. +.PP \fB-usepw\fR .IP If no other password method was supplied on the command @@ -524,6 +1274,9 @@ 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. +.IP +Note: \fB-unixpw\fR currently does not count as a password +method by this option. .PP \fB-storepasswd\fR \fIpass\fR \fIfile\fR .IP @@ -556,7 +1309,7 @@ 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 (1) +.IR inetd (8) or from display managers .IR xdm (1) @@ -642,7 +1395,7 @@ interpreted by x11vnc. Example: \fB-gone\fR 'xlock &' \fB-users\fR \fIlist\fR .IP If x11vnc is started as root (say from -.IR inetd (1) +.IR inetd (8) or from display managers .IR xdm (1) @@ -660,38 +1413,47 @@ 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) 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 Note that the -\fB-connect\fR file is also sometimes written to. -.IP -So be careful with this option since in many situations +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 +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 -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 +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 user "barney" by quickly using -"xhost +" when logging in may get x11vnc to switch -to user "fred". What happens next? +"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 make -it switch immediately regardless if the display +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 probably the only use of this option that increases security. .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=" +.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 of course. +be able to open the X display and any files of course. .IP The special user "guess=" means to examine the utmpx database (see @@ -701,18 +1463,18 @@ 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. Examples: "\fB-users\fR \fIlurk=\fR" and also -"\fB-users\fR \fIlurk=:0-1,bob,mary\fR" +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 @@ -752,7 +1514,7 @@ 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 (1) +.IR inetd (8) or .IR gdm (1) ), the \fB-users\fR option @@ -2025,7 +2787,7 @@ for a video camera that delivers the pixel data as mode if the bpp is 24. .IP video4linux: on Linux some attempt is made to handle -video devices (webcams or tv tuners) automatically. +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 @@ -2074,7 +2836,7 @@ 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 +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 @@ -2897,7 +3659,8 @@ http_url auth xauth users rootshift clipshift scale_str scaled_x scaled_y scale_numer scale_denom scale_fac scaling_blend scaling_nomult4 scaling_pad scaling_interpolate inetd privremote unsafe safer nocmds -passwdfile usepw using_shm +passwdfile unixpw unixpw_nis unixpw_list ssl ssl_pem +sslverify stunnel stunnel_pem https 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 |
