example

[authbind.git] / authbind.1

diff --git a/authbind.1 b/authbind.1
index a7bb5b54ac7960cf244aa83dab7949d65c7ec155..2cc5a7580760e953f252978c2bb0524bc899d180 100644 (file)
--- a/authbind.1
+++ b/authbind.1
@@ -17,14 +17,12 @@
 .\" along with this program; if not, write to the Free Software Foundation,
 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 
 .\"
 .\" along with this program; if not, write to the Free Software Foundation,
 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 
 .\"

-.\" $Id$
-.\"

 .TH AUTHBIND 1 "30th August 1998" "Debian Project" "Debian Linux manual"
 .SH NAME 
 authbind \- bind sockets to privileged ports without root
 .SH SYNOPSIS
 .TH AUTHBIND 1 "30th August 1998" "Debian Project" "Debian Linux manual"
 .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


@@ -37,6 +35,28 @@ will set up some environment variables, including an
 which will allow the program (including any subprocesses it may run)
 to bind to low-numbered (<512) ports if the system is configured to
 allow this.
 which will allow the program (including any subprocesses it may run)
 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,
 .SH ACCESS CONTROL
 Access to low numbered ports is controlled by permissions and contents
 of files in a configuration area,


@@ -62,10 +82,39 @@ call, usually
 .RI ( "Permission denied" ).
 .PP
 Secondly, if that test fails to resolve the matter,
 .RI ( "Permission denied" ).
 .PP
 Secondly, if that test fails to resolve the matter,

+.BI /etc/authbind/byaddr/ addr , port
+(any protocol) or failing that

 .BI /etc/authbind/byaddr/ addr : port
 .BI /etc/authbind/byaddr/ addr : port

-is tested, in the same manner as above.
+(IPv4 only)
+is tested, in the same manner as above.  Here
+.I addr
+is as from
+.BR inet_ntop ,
+and
+.I port
+is the (local) TCP or UDP port number, expressed as an unsigned
+integer in the minimal non-zero number of digits.
+.PP
+Thirdly, for IPv6 only: since the textual representation from
+.B inet_ntop
+is complicated to predict, a variant of
+.I addr
+is also tested which does not use the double colon abbreviation:
+each 16-byte chunk expressed in the minimal nonzero number
+of hex digits (i.e. with leading zeroes removed), the chunks
+being separated by colons as is conventional.
+.PP
+So for example an attempt to bind to [2620:106:e002:f00f::21]:80
+would result in authbind calling
+.I access(2)
+on
+.B /etc/authbind/byport/80
+and then
+.B /etc/authbind/byaddr/2620:106:e002:f00f::21,80
+and then
+.BR /etc/authbind/byaddr/2620:106:e002:f00f:0:0:0:21,80 .

 .PP
 .PP

-Thirdly, if the question is still unresolved, the file
+Fourthly, if the question is still unresolved, the file

 .BI /etc/authbind/byuid/ uid
 will be opened and read.  If the file does not exist then the binding
 is not authorised and
 .BI /etc/authbind/byuid/ uid
 will be opened and read.  If the file does not exist then the binding
 is not authorised and


@@ -75,15 +124,24 @@ will return
 .RI ( "Operation not permitted" ", or " "Not owner" ).
 If the file does exist it will be searched for a line of the form
 .nf
 .RI ( "Operation not permitted" ", or " "Not owner" ).
 If the file does exist it will be searched for a line of the form
 .nf

-.IB            addr / length : min\-port , max\-port
+.IR            addrmin [\fB\-\fR addrmax ]\fB,\fR portmin [\fB\-\fR portmax ]
+.IR            addr [\fB/\fR length ]\fB,\fR portmin [\fB\-\fR portmax ]
+.IB            addr4 / length : portmin , portmax

 .fi
 .fi

-matching the request (ie, the initial
+matching the request.
+The first form requires that the address lies in the
+relevant range (inclusive at both ends).
+The second and third forms require that the initial

 .I length
 bits of
 .I addr
 match those in the proposed
 .B bind
 .I length
 bits of
 .I addr
 match those in the proposed
 .B bind

-call, and the proposed port number lies is in the inclusive range
+call.  The third form is only available for IPv4 since IPv6 addresses
+contain colons.
+Addresses in the byuid file can
+be in any form acceptable to inet_pton.  In all cases
+the proposed port number must lie is in the inclusive range

 specified.  If such a line is found then the binding is authorised.
 Otherwise it is not, and
 .B bind
 specified.  If such a line is found then the binding is authorised.
 Otherwise it is not, and
 .B bind


@@ -91,15 +149,6 @@ will fail with
 .B ENOENT
 .RI ( "No such file or directory" ).
 .PP
 .B ENOENT
 .RI ( "No such file or directory" ).
 .PP

-In each case above,
-.TP
-.I port
-is the (local) TCP or UDP port number, expressed as an unsigned
-integer in the minimal non-zero number of digits, and
-.TP
-.I addr
-is the (local) IP address, as a dotted quad.
-.PP

 If a read error occurs, or the directory
 .B /etc/authbind
 cannot be accessed, then not only will
 If a read error occurs, or the directory
 .B /etc/authbind
 cannot be accessed, then not only will


@@ -111,7 +160,21 @@ files are silently ignored (as are lines whose
 .I addr
 has non-zero bits more than
 .I length
 .I addr
 has non-zero bits more than
 .I length

-from the top).
+from the top) or where some
+.I min
+is larger than
+.IR max .
+.PP
+Authorising binding to ports from 512 to 1023 inclusive is
+not recommended.  Some protocols (including some versions of NFS)
+authorise clients by seeing that they are using a port number in this
+range.  So by authorising a program to be a server for such a port,
+you are also authorising it to impersonate the whole host for those
+protocols.  To make sure that this isn't done by accident,
+if the port number requested is in the range 512-1023, authbind
+will expect the permission files to have an additional
+.B !
+at the start of their leafname.

 .SH MECHANISM
 The shared library loaded using
 .B LD_PRELOAD
 .SH MECHANISM
 The shared library loaded using
 .B LD_PRELOAD


@@ -156,7 +219,8 @@ the program's stderr, was well as returning -1 from
 .BR bind .
 .SH BUGS
 .B authbind
 .BR bind .
 .SH BUGS
 .B authbind

-currently only supports IPv4 sockets.  Programs which open other kinds
+currently only supports IPv4 and IPv6 sockets.
+Programs which open other kinds

 of sockets will not benefit from
 .BR authbind ,
 but it won't get in their way.
 of sockets will not benefit from
 .BR authbind ,
 but it won't get in their way.


@@ -168,6 +232,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 +254,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


@@ -192,19 +267,14 @@ wishes it to use authbind they could have it load the
 library explicitly rather than via
 .BR LD_PRELOAD .
 .PP
 library explicitly rather than via
 .BR LD_PRELOAD .
 .PP

-Some badly-written programs may have trouble because
+Some programs may have trouble because

 .B authbind
 spawns a child process `under their feet', causing (for example) a
 .BR fork (2)
 to happen and
 .B SIGCHLD
 .B authbind
 spawns a child process `under their feet', causing (for example) a
 .BR fork (2)
 to happen and
 .B SIGCHLD

-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 .
+signal to be delivered.  Unfortunately the Unix API does not make
+it possible to deal with this problem in a sane way.

 .PP
 The access control configuration scheme is somewhat strange.
 .SH FILES AND ENVIRONMENT VARIABLES
 .PP
 The access control configuration scheme is somewhat strange.
 .SH FILES AND ENVIRONMENT VARIABLES


@@ -231,16 +301,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),


@@ -249,7 +334,7 @@ otherwise lead to infinite recursion.
 .SH AUTHOR
 .B authbind
 and this manpage were written by Ian Jackson.  They are
 .SH AUTHOR
 .B authbind
 and this manpage were written by Ian Jackson.  They are

-Copyright (C)1998
+Copyright (C)1998,2012

 by him and released under the GNU General Public Licence; there is NO
 WARRANTY.  See
 .B /usr/doc/authbind/copyright
 by him and released under the GNU General Public Licence; there is NO
 WARRANTY.  See
 .B /usr/doc/authbind/copyright