ITS#6839

CHANGES

@@ -5,6 +5,8 @@ OpenLDAP 2.4.25 Engineering
 		Fixed libldap/lberl/util if/else usage (ITS#6832)
 		Fixed Windows odbc32 detection (ITS#6125)
 		Fixed test020 exit codes (ITS#6404)
+	Documentation
+		admin24 guide ldapi usage (ITS#6839)
 
 OpenLDAP 2.4.24 Release (2011/02/10)
 	Added LDIF line wrapping setting (ITS#6645)

doc/guide/admin/runningslapd.sdf

@@ -36,7 +36,16 @@ This option specifies alternative listener configurations.  The
 default is {{EX:ldap:///}} which implies {{TERM:LDAP}} over
 {{TERM:TCP}} on all interfaces on the default LDAP port 389.  You
 can specify specific host-port pairs or other protocol schemes (such
-as {{EX:ldaps://}} or {{EX:ldapi://}}).  For example, {{EX:-h
+as {{EX:ldaps://}} or {{EX:ldapi://}}).
+
+!block table
+URL        Protocol        Transport
+ldap:///   LDAP            TCP port 389
+ldaps:///  LDAP over SSL   TCP port 636
+ldapi:///  LDAP            IPC (Unix-domain socket)
+!endblock
+
+For example, {{EX:-h
 "ldaps:// ldap://127.0.0.1:666"}} will create two listeners: one
 for the (non-standard) {{EX:ldaps://}} scheme on all interfaces on
 the default {{EX:ldaps://}} port 636, and one for the standard
@@ -45,6 +54,18 @@ on port 666.  Hosts may be specified using using hostnames or
 {{TERM:IPv4}} or {{TERM:IPv6}} addresses.  Port values must be
 numeric.
 
+For LDAP over IPC, the pathname of the Unix-domain socket can be encoded
+in the URL. Note that directory separators must be 
+URL-encoded, like any other characters that are special to URLs.
+Thus the socket {{EX:/usr/local/var/ldapi}} must be encoded as
+
+>	ldapi://%2Fusr%2Flocal%2Fvar%2Fldapi
+
+ldapi: is described in detail in {{Using LDAP Over IPC Mechanisms}} [{{REF:Chu-LDAPI}}]
+
+Note that the ldapi:/// transport is not widely implemented: non-OpenLDAP clients
+may not be able to use it.
+
 >	-n <service-name>
 
 This option specifies the service name used for logging and

doc/guide/admin/sasl.sdf

@@ -72,10 +72,13 @@ and large enterprises.  Use of {{SECT:GSSAPI}} and {{SECT:KERBEROS_V4}}
 are discussed below.
 
 The EXTERNAL mechanism utilizes authentication services provided
-by lower level network services such as {{TERM:TLS}} (TLS).  When
+by lower level network services such as {{TERM[expand]TLS}} ({{TERM:TLS}}).  When
 used in conjunction with {{TERM:TLS}} {{TERM:X.509}}-based public
-key technology, EXTERNAL offers strong authentication.  Use of
-EXTERNAL is discussed in the {{SECT:Using TLS}} chapter.
+key technology, EXTERNAL offers strong authentication.
+TLS is discussed in the {{SECT:Using TLS}} chapter.
+
+EXTERNAL can also be used with the {{EX:ldapi:///}} transport, as
+Unix-domain sockets can report the UID and GID of the client process.
 
 There are other strong authentication mechanisms to choose from,
 including {{TERM:OTP}} (one time passwords) and {{TERM:SRP}} (secure
@@ -289,6 +292,41 @@ The server will infer an authorization identity from authentication
 identity (as described below).
 
 
+H3: EXTERNAL
+
+The SASL EXTERNAL mechanism makes use of an authentication performed
+by a lower-level protocol: usually {{TERM:TLS}} or Unix {{TERM:IPC}}
+
+Each transport protocol returns Authentication Identities in its own
+format:
+
+H4: TLS Authentication Identity Format
+
+This is the Subject DN from the client-side certificate.
+Note that DNs are displayed differently by LDAP and by X.509, so
+a certificate issued to
+>	C=gb, O=The Example Organisation, CN=A Person
+
+will produce an authentication identity of:
+
+>	cn=A Person,o=The Example Organisation,c=gb
+
+Note that you must set a suitable value for TLSVerifyClient to make the server
+request the use of a client-side certificate. Without this, the SASL EXTERNAL
+mechanism will not be offered.
+Refer to the {{SECT:Using TLS}} chapter for details.
+
+H4: IPC (ldapi:///) Identity Format
+
+This is formed from the Unix UID and GID of the client process:
+
+>	gidNumber=<number>+uidNumber=<number>,cn=peercred,cn=external,cn=auth
+
+Thus, a client process running as {{EX:root}} will be:
+
+>	gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
+
+
 H3: Mapping Authentication Identities
 
 The authentication mechanism in the slapd server will use SASL

doc/guide/preamble.sdf

@@ -308,4 +308,5 @@ RFC4518|PS|Lightweight Directory Access Protocol (LDAP): Internationalized Strin
 RFC4519|PS|Lightweight Directory Access Protocol (LDAP): Schema for User Applications|http://www.rfc-editor.org/rfc/rfc4519.txt
 RFC4520|BCP|IANA Considerations for LDAP|http://www.rfc-editor.org/rfc/rfc4520.txt
 RFC4533|X|The Lightweight Directory Access Protocol (LDAP) Content Synchronization Operation|http://www.rfc-editor.org/rfc/rfc4533.txt
+Chu-LDAPI|ID|Using LDAP Over IPC Mechanisms|http://tools.ietf.org/html/draft-chu-ldap-ldapi-00
 !endblock

doc/man/man8/slapd.8

@@ -193,6 +193,22 @@ options.  Hosts may be specified by name or IPv4 and IPv6 address formats.
 Ports, if specified, must be numeric.  The default ldap:// port is \fB389\fP
 and the default ldaps:// port is \fB636\fP.
 
+For LDAP over IPC,
+.B name 
+is the name of the socket, and no
+.B port
+is required, nor allowed; note that directory separators must be 
+URL-encoded, like any other characters that are special to URLs; 
+so the socket
+
+        /usr/local/var/ldapi
+
+must be specified as
+
+        ldapi://%2Fusr%2Flocal%2Fvar%2Fldapi
+
+The default location for the IPC socket is LOCALSTATEDIR/run/ldapi
+
 The listener permissions are indicated by
 "x\-mod=\-rwxrwxrwx", "x\-mod=0777" or "x\-mod=777", where any 
 of the "rwx" can be "\-" to suppress the related permission, while any