(ITS#9488) documentation: slapo-unique syntax explanation unclear

[gray@nxg.name]

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