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
--On Friday, September 13, 2019 6:07 PM +0000 gray@nxg.name wrote: > 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) Note: this is now ITS#9079. --Quanah -- Quanah Gibson-Mount Product Architect Symas Corporation Packaged, certified, and supported LDAP solutions powered by OpenLDAP: <http://www.symas.com>
(In reply to gray@nxg.name from comment #0) > 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. This is a typo, which will be fixed. > * 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 The concept of a "domain" is a key part of the mathematical concept of "sets". As this is clearly talking about sets, the definition of domain follows. > * If multiple URIs are specified in a 'domain' Again, this goes back to the mathematical concept of sets. > * 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? This is already explicitly answered in the man page: "Strictness applies to all URIs within a uniqueness domain" thus it must be combined with the full set of URIs in a given statement.
https://git.openldap.org/openldap/openldap/-/merge_requests/277
> > * 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 > > > The concept of a "domain" is a key part of the mathematical concept of "sets". As this is clearly talking about sets, the definition of domain follows. We may be thinking of different set theories, but in the mathematical set theory I'm familiar with, there is no notion of 'domain'. Functions have domains, codomains and ranges which are each sets, but that is part of the theory of functions, not of sets. Not that it matters, because 'domain' has a variety of meanings in computing contexts, so it does no harm to be precise here. Since the text just above this in the manpage talks of 'scope', in a sense which appears to at least overlap with 'domain' here, I merely suggest that the text explain what it means by 'domain'. For concreteness, can I suggest: Each `unique_uri` option defines a 'uniqueness domain' consisting of the set of attributes which would be returned by the specified (RFC 4516) LDAP URI, or the union of the sets of attributes returned by the URIs, if there is more than one. The overlay ensures that no two attributes in this set have the same value. In a 'strict' uniqueness domain (when the keyword 'strict' is present), at most one attribute in the domain may have a null value; in a non-strict domain more than one attribute may have a null value. This uniqueness constraint is imposed independently for the attributes in each uniqueness domain. ...and delete the paragraph 'It is possible...' [If 'scope' is a different notion from 'domain', then the text might benefit from some clarification about what the difference is; if they are the same notion, then it might be useful to use the same term for both, or else the careful reader will worry that there is a distinction being made that they don't understand.] > > * 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? > > > This is already explicitly answered in the man page: > > "Strictness applies to all URIs within a uniqueness domain" thus it must be combined with the full set of URIs in a given statement. True. As implied above, it might be useful to relocate the remark about what 'strict' means, but the answer to my question was indeed implicit in the text as it stands. To be clear, I reiterate that I'm not suggesting the text is inaccurate, simply that it is not as clear as it could be, and I wouldn't bother suggesting documentation edits if the OpenLDAP documentation were not already unusually high quality. Also, when I first read the manpage I largely got the point pretty quickly (it's not a complicated notion), and it's only when I re-read carefully that I started to have doubts.
Commits: • 9d5267e1 by Quanah Gibson-Mount at 2021-03-09T19:12:49+00:00 ITS#9079 - Fix minor issues with slapo-unique man page