Improvements to -unixpw_cmd and -unixpw_nis.

Experimental X11VNC_WATCH_DX_DY=1 for buggy theme menus,
see: http://ubuntuforums.org/showthread.php?t=1223490

1 files changed, 111 insertions, 47 deletions

diff --git a/x11vnc/x11vnc.1 b/x11vnc/x11vnc.1
index c2da5ee..6c93474 100644
--- a/x11vnc/x11vnc.1
+++ b/x11vnc/x11vnc.1
@@ -1,8 +1,8 @@
 .\" This file was automatically generated from x11vnc -help output.
-.TH X11VNC "1" "July 2009" "x11vnc " "User Commands"
+.TH X11VNC "1" "August 2009" "x11vnc " "User Commands"
 .SH NAME
 x11vnc - allow VNC connections to real X11 displays
-         version: 0.9.9, lastmod: 2009-07-11
+         version: 0.9.9, lastmod: 2009-08-10
 .SH SYNOPSIS
 .B x11vnc
 [OPTION]...
@@ -347,8 +347,8 @@ is needed for the latter, feel free to ask).
 \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.
+less than 1 shrink the fb, larger ones expand it. Note:
+the image may not be sharp and response may be slower.
 If \fIfraction\fR contains a decimal point "." it
 is taken as a floating point number, alternatively
 the notation "m/n" may be used to denote fractions
@@ -568,7 +568,7 @@ is running as root (e.g. via
 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
+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:
@@ -871,14 +871,14 @@ full-access passwords)
 \fB-unixpw\fR \fI[list]\fR
 .IP
 Use Unix username and password authentication.  x11vnc
-uses the 
+will use the 
 .IR su (1)
-program to verify the user's password.
-[list] is an optional comma separated list of allowed
-Unix usernames.  If the [list] string begins with the
-character "!" then the entire list is taken as an
-exclude list.  See below for per-user options that can
-be applied.
+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
@@ -896,8 +896,9 @@ 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.
+before deployment to make sure it is working properly.
+x11vnc will attempt to be conservative and reject a
+login if anything abnormal occurs.
 .IP
 One case to note: FreeBSD and the other BSD's by
 default it is impossible for the user running x11vnc to
@@ -932,7 +933,7 @@ 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).
+network. (see the description of \fB-stunnel\fR below).
 .IP
 Note: as a convenience, if you 
 .IR ssh (1)
@@ -966,7 +967,7 @@ local connections from that machine are accepted).
 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).
+network.)
 .IP
 Regarding reverse connections (e.g. \fB-R\fR connect:host
 and \fB-connect\fR host), when the \fB-localhost\fR constraint is
@@ -984,7 +985,7 @@ 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
+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
@@ -992,13 +993,13 @@ where "opts" is a "+" separated list of
 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
+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 any value of options
-associated with it does apply as normal.
+"*" to set a global option.  If [list] begins with the
+"!" character then "*" is ignored for checking if
+the user is allowed, but the option values associated
+with it do apply as normal.
 .IP
 There are also some utilities for testing password
 if [list] starts with the "%" character.  See the
@@ -1032,18 +1033,27 @@ user can authenticate ANY user.
 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).
+but it is unlikely it will work (as an ordinary user)
+for most modern environments unless NIS is available.
+On the other hand, when x11vnc is run as root it will
+be able to to access /etc/shadow even if NIS is not
+available (note running as root is often done when
+running x11vnc from inetd and xdm/gdm/kdm).
 .IP
 Looked at another way, if you do not want to use the
 .IR su (1)
-method provided by \fB-unixpw,\fR 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.
+method provided by \fB-unixpw\fR (i.e. su_verify()), you
+can run x11vnc as root and use \fB-unixpw_nis.\fR  Any users
+with passwords in /etc/shadow can then be authenticated.
+.IP
+In \fB-unixpw_nis\fR mode, under no circumstances is x11vnc's
+user password verifying function based on su called
+(i.e. the function su_verify() that runs /bin/su
+in a pseudoterminal to verify passwords.)  However,
+if \fB-unixpw_nis\fR is used in conjunction with the \fB-find\fR
+and \fB-create\fR \fB-display\fR WAIT:... modes then, if x11vnc is
+running as root, /bin/su may be called externally to
+run the find or create commands.
 .PP
 \fB-unixpw_cmd\fR \fIcmd\fR
 .IP
@@ -1051,18 +1061,66 @@ 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.
+line of its stdin will be the username and the second
+line the received password.  If the command exits
+with status 0 (success) the VNC user will be accepted.
+It will be rejected for any other return status.
+.IP
+Dynamic passwords and non-unix passwords, e.g. LDAP,
+can be implemented this way by providing your own custom
+helper program.  Note that the remote viewer is given 3
+tries to enter the correct password, and so the program
+may be called in a row that many (or more) times.
+.IP
+If a list of allowed users is needed to limit who can
+log in, use \fB-unixpw\fR [list] in addition to this option.
+.IP
+In FINDDISPLAY and FINDCREATEDISPLAY modes the \fIcmd\fR
+will also be run with the RFB_UNIXPW_CMD_RUN env. var.
+non-empty and set to the corresponding display
+find/create command.  The first two lines of input are
+the username and passwd as in the normal case described
+above.  To support FINDDISPLAY and FINDCREATEDISPLAY,
+\fIcmd\fR should run the requested command as the user
+(and most likely refusing to run it if the password is
+not correct.)  Here is an example script (note it has
+a hardwired bogus password "abc"!)
+.IP
+#!/bin/sh
+# Example x11vnc \fB-unixpw_cmd\fR script.
+# Read the first two lines of stdin (user and passwd)
+read user
+read pass
+.IP
+debug=0
+if [ $debug = 1 ]; then
+echo "user: $user" 1>&2
+echo "pass: $pass" 1>&2
+env | egrep \fB-i\fR 'rfb|vnc' 1>&2
+fi
+.IP
+# Check if the password is valid.
+# (A real example would use ldap lookup, etc!)
+if [ "X$pass" != "Xabc" ]; then
+exit 1	# incorrect password
+fi
+.IP
+if [ "X$RFB_UNIXPW_CMD_RUN" = "X" ]; then
+exit 0	# correct password
+else
+# Run the requested command (finddisplay)
+if [ $debug = 1 ]; then
+echo "run: $RFB_UNIXPW_CMD_RUN" 1>&2
+fi
+exec /bin/su - "$user" \fB-c\fR "$RFB_UNIXPW_CMD_RUN"
+fi
+.IP
+In \fB-unixpw_cmd\fR mode, under no circumstances is x11vnc's
+user password verifying function based on su called
+(i.e. the function su_verify() that runs /bin/su in a
+pseudoterminal to verify passwords.)  It is up to the
+supplied unixpw_cmd to do user switching if desired
+and if it has the permissions to do so.
 .PP
 \fB-find\fR
 .IP
@@ -1214,9 +1272,15 @@ xauthority data for the display. For example;
 .IP
 xauth extract - $DISPLAY"
 .IP
-In the case of \fB-unixpw\fR (but not \fB-unixpw_nis),\fR then the
-cmd= command is run as the user who just authenticated
-via the login and password prompt.
+In the case of \fB-unixpw\fR (and \fB-unixpw_nis\fR only if x11vnc
+is running as root), then the cmd= command is run
+as the user who just authenticated via the login and
+password prompt.
+.IP
+In the case of \fB-unixpw_cmd,\fR the commands will also be
+run as the logged-in user, as long as the user-supplied
+helper program supports RFB_UNIXPW_CMD_RUN (see the
+\fB-unixpw_cmd\fR option.)
 .IP
 Also in the case of \fB-unixpw,\fR the user logging in can
 place a colon at the end of her username and supply
@@ -5827,7 +5891,7 @@ max time in ms to wait for RFB client
 \fB-rfbauth\fR \fIpasswd-file\fR
 .IP
 use authentication on RFB protocol
-(use 'storepasswd' to create a password file)
+(use 'x11vnc \fB-storepasswd\fR pass file' to create a password file)
 .PP
 \fB-rfbversion\fR \fI3.x\fR
 .IP