Full_Name: Norman Gray Version: 2.4.48 OS: FreeBSD 12.0 URL: ftp://ftp.openldap.org/incoming/ Submission from: (NULL) (130.209.45.140)

Documentation bug

The documentation for the `unique_uri` or `olcUniqueURI` attribute is very compact, with the result that it is not clear what counts as correct syntax, nor what are the semantics of the specification.

I'm not suggesting that the text is necessarily _inaccurate_, but that it is too brief. That is, someone who already understand the syntax and semantics will probably not notice anything wrong with this paragraph; someone who doesn't already understand (eg, me) will struggle.

slapo-unique(5) says that the syntax here is:

unique_uri <[strict ][ignore ]URI[URI...]...> Configure the base, attributes, scope, and filter for uniqueness checking. Multiple URIs may be specified within a domain, allowing complex selections of objects. Multiple unique_uri statements or olcUniqueURI attributes will create independent domains, each with their own independent lists of URIs and ignore/strict settings.

Keywords strict and ignore have to be enclosed in quotes (") together with the URI.

The LDAP URI syntax is a subset of RFC-4516, and takes the form:

ldap:///[base dn]?[attributes...]?scope[?filter]

I understand from this text the following:

* One can specify multiple URIs in the value of a olcUniqueURI attribute. I _guess_ these can be space-separated, even though that isn't shown in this syntax. * Each URI defines a set of object attributes * One can have multiple olcUniqueURI attributes, _each of which_ creates a 'domain' * This doesn't say what a 'domain' is, but I _guess_ that it means that all of the attributes which match the search are forced, by this overlay, to be unique, but that there are no mutual uniqueness requirements between separate olcUniqueURI/'domain' specifications * If multiple URIs are specified in a 'domain', or olcUniqueURI attribute, then (wild guess) the union of the attributes matched by each URI is unique; I doubt it means the intersection of the result sets (I guess that because that's the only thing that sounds sensible; the phrase 'complex selections of objects' doesn't clarify) * It's not clear where the quotes go, when combining with 'strict' or 'ignore' (I guess "strict ldap://..."). * Can 'strict' or 'ignore' be combined with the second or subsequent URIs? The syntax suggests not.

I don't think the above understanding is correct, because when I specify a olcUniqueURI attribute with multiple URIs, I get an error (see ITS#9486 and thread https://www.openldap.org/lists/openldap-technical/201909/msg00031.html). At any rate, I have little confidence that I have interpreted the text correctly, and the above is the result of several careful readings and some guesswork.

If the above, or something like it, is roughly correct, I could draft an alternative paragraph, if that would be useful.

If the manpage included more than one example, that would be _extremely_ useful.

I'll mention in passing that in servers/slapd/overlays/unique.c, the comment above `unique_new_domain` says instead

* domain_specs look like * * [strict ][ignore ]uri[[ uri]...] * e.g. "ldap:///ou=foo,o=bar?uid?sub ldap:///ou=baz,o=bar?uid?sub" * "strict ldap:///ou=accounts,o=bar?uid,uidNumber?one" * etc