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
{{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
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
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 usually the Subject DN from the client-side certificate.
+The order of the components will be changed to follow LDAP conventions,
+so a certificate issued to {{EX: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
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
projects / openldap / commitdiff