document the LDAP builtin map in librewrite (ITS#4602)

doc/man/man5/slapo-rwm.5

@@ -393,6 +393,51 @@ The count applies to the rewriting operation as a whole, not
 to any single rule; an optional per-rule limit can be set.
 This limit is overridden by setting specific per-rule limits
 with the `M{n}' flag.
+
+.SH "MAPS"
+Currently, few maps are builtin and there are no provisions for developers
+to register new map types at runtime.
+
+Supported maps are:
+.TP
+.B LDAP <URI> [bindwhen=<when>] [version=<version>] [binddn=<DN>] [credentials=<cred>]
+The
+.B LDAP
+map expands a value by performing a simple LDAP search.
+Its configuration is based on a mandatory URI, whose
+.B attrs
+portion must contain exactly one attribute
+(use
+.B entryDN
+to fetch the DN of an entry).
+If a multi-valued attribute is used, only the first value is considered.
+
+The parameter
+.B bindwhen
+determines when the connection is established.
+It can take the values
+.BR now ,
+.BR later ,
+and
+.BR everytime ,
+respectively indicating that the connection should be created at startup,
+when required, or any time it is used.
+In the former two cases, the connection is cached, while in the latter
+a fresh new one is used all times.  This is the default.
+
+The parameters
+.B binddn
+and
+.B credentials
+represent the DN and the password that is used to perform an authenticated
+simple bind before performing the search operation; if not given,
+an anonymous connection is used.
+
+The parameter
+.B version
+can be 2 or 3 to indicate the protocol version that must be used.
+The default is 3.
+
 .SH "REWRITE CONFIGURATION EXAMPLES"
 .nf
 # set to `off' to disable rewriting

libraries/librewrite/ldapmap.c

@@ -23,6 +23,13 @@
 #include "rewrite-int.h"
 #include "rewrite-map.h"
 
+typedef enum {
+	MAP_LDAP_UNKNOWN,
+	MAP_LDAP_EVERYTIME,
+	MAP_LDAP_NOW,
+	MAP_LDAP_LATER
+} bindwhen_t;
+
 /*
  * LDAP map data structure
  */
@@ -33,10 +40,7 @@ struct ldap_map_data {
 	char                           *lm_binddn;
 	struct berval			lm_cred;
 
-#define MAP_LDAP_EVERYTIME		0x00
-#define MAP_LDAP_NOW			0x01
-#define MAP_LDAP_LATER			0x02
-	int                             lm_when;
+	bindwhen_t			lm_when;
 
 	LDAP                           *lm_ld;
 
@@ -91,7 +95,7 @@ map_ldap_parse(
 )
 {
 	struct ldap_map_data *data;
-	char *p;
+	char *p, *uri;
 
 	assert( info != NULL );
 	assert( fname != NULL );
@@ -110,13 +114,18 @@ map_ldap_parse(
 		return NULL;
 	}
 
-	data->lm_url = strdup( argv[ 0 ] );
+	uri = argv[ 0 ];
+	if ( strncasecmp( uri, "uri=", STRLENOF( "uri=" ) ) == 0 ) {
+		uri += STRLENOF( "uri=" );
+	}
+
+	data->lm_url = strdup( uri );
 	if ( data->lm_url == NULL ) {
 		map_ldap_free( data );
 		return NULL;
 	}
 	
-	if ( ldap_url_parse( argv[ 0 ], &data->lm_lud ) != REWRITE_SUCCESS ) {
+	if ( ldap_url_parse( uri, &data->lm_lud ) != REWRITE_SUCCESS ) {
 		Debug( LDAP_DEBUG_ANY,
 				"[%s:%d] illegal URI '%s'\n",
 				fname, lineno, argv[ 0 ] );
@@ -124,6 +133,7 @@ map_ldap_parse(
 		return NULL;
 	}
 
+	/* trim everything after [host][:port] */
 	p = strchr( data->lm_url, '/' );
 	assert( p[ 1 ] == '/' );
 	if ( ( p = strchr( p + 2, '/' ) ) != NULL ) {
@@ -268,6 +278,10 @@ map_ldap_parse(
 		}
 	}
 
+	if ( data->lm_when == MAP_LDAP_UNKNOWN ) {
+		data->lm_when = MAP_LDAP_EVERYTIME;
+	}
+
 	return ( void * )data;
 }