X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=authbind.git;a=blobdiff_plain;f=authbind.1;h=2b372eaf08396cf2c5bc5e6af200e35e88999404;hp=10531b59662dcadeeb89c5feed26c1a205e629b5;hb=15271c2345b0eb313ab73e5a6d2b9c87f8fe266e;hpb=3f781654282c8c85317394dfd874483c4321fac1

diff --git a/authbind.1 b/authbind.1
index 10531b5..2b372ea 100644
--- a/authbind.1
+++ b/authbind.1
@@ -23,8 +23,8 @@
 .SH NAME 
 authbind \- bind sockets to privileged ports without root
 .SH SYNOPSIS
-.BI authbind " program"
-.RI [ argument " ...]"
+.BR authbind
+.RI [ options "] " program " [" argument " ...]"
 .SH DESCRIPTION
 .B authbind
 allows a program which does not or should not run as root to bind to
@@ -35,8 +35,30 @@ You must invoke the program using
 will set up some environment variables, including an
 .BR LD_PRELOAD ,
 which will allow the program (including any subprocesses it may run)
-to bind to low-numbered (<1024) ports if the system is configured to
+to bind to low-numbered (<512) ports if the system is configured to
 allow this.
+.SH OPTIONS
+.TP
+.B --deep
+Normally,
+.B authbind
+arranges for only the program which it directly invokes to be affected
+by its special version of
+.BR bind (2).
+If you specify
+.B --deep
+then all programs which that program invokes directly or indirectly
+will be affected, so long as they do not unset the environment
+variables set up by
+.BR authbind .
+.TP
+.BI --depth " levels"
+Causes
+.B authbind
+to affect programs which are
+.I levels
+deep in the calling graph.  The default is
+.BR "--depth 1" .
 .SH ACCESS CONTROL
 Access to low numbered ports is controlled by permissions and contents
 of files in a configuration area,
@@ -168,6 +190,13 @@ makes an
 installation specific to a particular C library.  This version is for
 GNU/Linux libc6 (glibc2).
 .PP
+.B authbind
+may not operate correctly with multithreaded programs.  It is
+inherently very difficult (if not impossible) to perform the kind of
+trickery that authbind does while preventing all undesirable
+interactions between authbind's activities and those of (say) a
+threading runtime system.
+.PP
 It is quite possible that
 .B authbind
 and other programs and facilities which use
@@ -183,7 +212,11 @@ means in this context).
 .B authbind
 is ineffective with setuid programs, because they do not honour
 .B LD_PRELOAD
-for security reasons.  Of course a setuid-root program does not need
+references outside the system directories, for security reasons.  (In
+fact, setuid programs should not honour
+.B LD_PRELOAD
+at all.)
+Of course a setuid-root program does not need
 .BR authbind ,
 but it might be useful to apply it to program which are setuid to
 another user or setgid.  If the author or builder of such a programs
@@ -201,6 +234,11 @@ to happen and
 signal to be delivered.  Programs should not rely on standard
 libraries not doing these things.
 .PP
+Ports from 512 to 1023 inclusive cannot be used with
+.B authbind
+because that would create a security hole, in conjection with
+.BR rshd .
+.PP
 The access control configuration scheme is somewhat strange.
 .SH FILES AND ENVIRONMENT VARIABLES
 .TP
@@ -226,16 +264,31 @@ If set, forces
 .B authbind
 to use its value as the path to the shared library to put in
 .BR LD_PRELOAD ,
-instead of the compiled-in value.
+instead of the compiled-in value.  In any case, unless
+.B --deep
+was specified,
+.B authbind
+will set this variable to the name of the library actually added to
+.BR LD_PRELOAD ,
+so that the library can find and remove the right entry.
 .TP
-.I AUTHBIND_NESTED
-Do not set this variable.  It is set to
-.B 1
-by
-.B libauthbind
-when it invokes the helper program.  This allows detection of the
-situation where the helper has not been installed setuid, which would
-otherwise lead to infinite recursion.
+.I AUTHBIND_LEVELS
+This variable is set by
+.B authbind
+to the number of levels left from the
+.B --depth
+or
+.B --deep
+option, minus one.  It is decremented during
+.B _init
+by the library on each program call, and the library will remove
+itself from the
+.B LD_PRELOAD
+when it reaches zero.  The special value
+.B y
+means
+.B --deep
+was specified.
 .SH SEE ALSO
 .BR bind (2),
 .BR authbind\-helper (8),