* Set SHELL=/bin/bash in debian/rules. Closes #374586.

[authbind.git] / authbind.1

diff --git a/authbind.1 b/authbind.1
index 10531b59662dcadeeb89c5feed26c1a205e629b5..2b372eaf08396cf2c5bc5e6af200e35e88999404 100644 (file)
--- a/authbind.1
+++ b/authbind.1
@@ -23,8 +23,8 @@
 .SH NAME 
 authbind \- bind sockets to privileged ports without root
 .SH SYNOPSIS
 .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
 .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)
 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.
 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,
 .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
 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
 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
 .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
 .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
 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
 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 ,
 .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
 .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),
 .SH SEE ALSO
 .BR bind (2),
 .BR authbind\-helper (8),