X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=authbind.git;a=blobdiff_plain;f=authbind.1;h=d73e998990a92e6139d5c2ef6165f7aaac8e0569;hp=09f9fc2c2b02e52c8cc6e0ffbe8b38c0ecf4514c;hb=9d4eb04ba356aac58d96bbb2bdf81bd69ba68122;hpb=ea186a6c113d2397f73596952a65ecd4e3d51c76 diff --git a/authbind.1 b/authbind.1 index 09f9fc2..d73e998 100644 --- a/authbind.1 +++ b/authbind.1 @@ -17,8 +17,6 @@ .\" 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 @@ -65,7 +63,7 @@ of files in a configuration area, .BR /etc/authbind . .PP Firstly, -.BR /etc/authbind/byport/ [ ! ]\fIport\fR +.BI /etc/authbind/byport/ port is tested. If this file is accessible for execution to the calling user, according to .BR access (2), @@ -84,11 +82,30 @@ call, usually .RI ( "Permission denied" ). .PP Secondly, if that test fails to resolve the matter, -.BR /etc/authbind/byaddr/ \fIaddr\fR : [ ! ]\fIport\fR -is tested, in the same manner as above. +.BI /etc/authbind/byaddr/ addr , port +(any protocol) or failing that +.BI /etc/authbind/byaddr/ addr : port +(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 -Thirdly, if the question is still unresolved, the file -.BR /etc/authbind/byuid/ [ ! ]\fIuid\fR +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 .B bind @@ -97,18 +114,23 @@ 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 -.IB addr4 / length : min\-port , max\-port -.IR addrmin [\fB-\fR addrmax ]\fB:\fR min\-port \fB,\fR 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 -matching the request. The first form requires that 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 -call. The second form requires that the address lies in the -relevant range (inclusive at both ends). Addresses can -be in any form acceptable to inet_pton. In both cases +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 @@ -117,15 +139,6 @@ will fail with .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 @@ -133,22 +146,51 @@ cannot be accessed, then not only will fail, but an error message will be printed to stderr. Unrecognised lines in .BI /etc/authbind/byuid/ uid -files are silently ignored (as are lines whose +files are silently ignored, as are lines whose .I addr has non-zero bits more than .I length -from the top). -.TP +from the top or where some +.I min +is larger than +.IR max . +.SH EXAMPLE +So for example an attempt by uid 432 +to bind to port 80 of address [2620:106:e002:f00f::21] +would result in authbind calling +.I access(2) +on, in order, +.RS +.B /etc/authbind/byport/80 +.br +.B /etc/authbind/byaddr/2620:106:e002:f00f::21,80 +.br +.B /etc/authbind/byaddr/2620:106:e002:f00f:0:0:0:21,80 +.RE +If none of these files exist, authbind will read +.RS +.B /etc/authbind/byuid/432 +.RE +and search for a line to permit +the relevant access; examples of lines which would do so are: +.RS +.B 2620:106:e002:f00f::21,80 +.br +.B ::/0,80 +.RE +.SH PORTS 512-1023 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, all the files -checked and read will have the additional +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 ! -character. +at the start of their leafname. .SH MECHANISM The shared library loaded using .B LD_PRELOAD @@ -241,14 +283,14 @@ wishes it to use authbind they could have it load the 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 -signal to be delivered. Programs should not rely on standard -libraries not doing these things. +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 @@ -308,7 +350,7 @@ was specified. .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