From 4a68e78a5fcba47b43e3a8b45e7c8451fe51a6e5 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Wed, 01 Feb 2012 15:39:35 +0000
Subject: [PATCH] Mention extensible matching rule indexes and matching on "later than" and "earlier than"
---
opendj-sdk/opendj3/src/main/docbkx/admin-guide/chap-indexing.xml | 45 ++++++++++++++
opendj-sdk/opendj3/src/main/docbkx/admin-guide/chap-ldap-operations.xml | 81 ++++++++++++++++++++++++++
2 files changed, 124 insertions(+), 2 deletions(-)
diff --git a/opendj-sdk/opendj3/src/main/docbkx/admin-guide/chap-indexing.xml b/opendj-sdk/opendj3/src/main/docbkx/admin-guide/chap-indexing.xml
index c3e9833..0cb8228 100644
--- a/opendj-sdk/opendj3/src/main/docbkx/admin-guide/chap-indexing.xml
+++ b/opendj-sdk/opendj3/src/main/docbkx/admin-guide/chap-indexing.xml
@@ -191,6 +191,19 @@
VLV indexes using the Control Panel, and copy the command-line
equivalent from the Details pane for the operation, if necessary.</para>
</section>
+
+ <section xml:id="indexes-extensible">
+ <title>Extensible Matching Rule Index</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Extensible matching rule</secondary>
+ </indexterm>
+
+ <para>In some cases you need an index for a matching rule other than those
+ described above. For example, OpenDJ supports generalized time based
+ matching so applications can search for all times later than, or earlier
+ than a specified time.</para>
+ </section>
</section>
<section xml:id="configure-indexes">
@@ -247,7 +260,7 @@
<secondary>Approximate</secondary>
</indexterm>
- <para>The following example configures and approximate index for
+ <para>The following example configures an approximate index for
<literal>cn</literal> (common name).</para>
<screen>$ dsconfig
@@ -262,6 +275,36 @@
--trustAll
--no-prompt</screen>
</example>
+
+ <example xml:id="extensible-match-index-example">
+ <title>Configure an Extensible Match Index</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Extensible matching rule</secondary>
+ </indexterm>
+
+ <para>The OpenDJ Control Panel New Index window does not help you set up
+ extensible matching rule indexes. Use the <command>dsconfig</command>
+ command instead.</para>
+
+ <para>The following example configures an extensible matching rule
+ index for "later than" and "earlier than" generalized time matching on
+ a <literal>lastLoginTime</literal> attribute.</para>
+
+ <screen>$ dsconfig
+ create-local-db-index
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --backend-name userRoot
+ --set index-type:extensible
+ --set index-extensible-matching-rule:1.3.6.1.4.1.26027.1.4.5
+ --set index-extensible-matching-rule:1.3.6.1.4.1.26027.1.4.6
+ --index-name lastLoginTime
+ --trustAll
+ --no-prompt</screen>
+ </example>
</section>
<section xml:id="configure-vlv">
diff --git a/opendj-sdk/opendj3/src/main/docbkx/admin-guide/chap-ldap-operations.xml b/opendj-sdk/opendj3/src/main/docbkx/admin-guide/chap-ldap-operations.xml
index 0f43bf8..20a1278 100644
--- a/opendj-sdk/opendj3/src/main/docbkx/admin-guide/chap-ldap-operations.xml
+++ b/opendj-sdk/opendj3/src/main/docbkx/admin-guide/chap-ldap-operations.xml
@@ -223,8 +223,87 @@
telephoneNumber: +1 408 555 1862
sn: Jensen</screen>
</example>
+
+ <example xml:id="extensible-match-search">
+ <title>Search: List Active Accounts</title>
+
+ <para>OpenDJ supports extensible matching rules, meaning you can pass in
+ filters specifying a matching rule OID that extends your search beyond what
+ you can do with standard LDAP. One specific matching rule of this type that
+ OpenDJ supports is the generalized time based "later than" and "earlier
+ than" matching rules. See the example, <link
+ xlink:role="http://docbook.org/xlink/role/olink"
+ xlink:href="admin-guide#extensible-match-index-example"><citetitle>Configure
+ an Extensible Match Index</citetitle></link>, showing how to build an index
+ for these matching rules.</para>
+
+ <para>You can use these matching rules to list, for example, all users who
+ have authenticated recently.</para>
+
+ <para>First set up an attribute to store a last login timestamp.
+ You can do this by adding a schema file for the attribute.</para>
+
+ <screen>$ cat /path/to/OpenDJ/config/schema/98-lastLogin.ldif
+#
+# Schema definition for a generalizedTimeMatch lastLoginTime attribute
+#
+dn: cn=schema
+objectClass: top
+objectClass: ldapSubentry
+objectClass: subschema
+attributeTypes: ( lastLoginTime-oid
+ NAME 'lastLoginTime'
+ DESC 'Last time the user logged in'
+ EQUALITY generalizedTimeMatch
+ ORDERING generalizedTimeOrderingMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
+ SINGLE-VALUE
+ NO-USER-MODIFICATION
+ USAGE directoryOperation
+ X-ORIGIN 'OpenDJ examples' )
+
+</screen>
+
+ <para>Restart OpenDJ after you add the schema file.</para>
+
+ <screen>$ stop-ds --restart</screen>
+
+ <para>Configure the applicable password policy to write the last login
+ timestamp when a user authenticates. The following command configures the
+ default password policy to write the timestamp in generalized time format
+ to the <literal>lastLoginTime</literal> operational attribute on the user's
+ entry.</para>
+
+ <screen>$ dsconfig
+ set-password-policy-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --policy-name "Default Password Policy"
+ --set last-login-time-attribute:lastLoginTime
+ --set last-login-time-format:"yyyyMMddHHmmss'Z'"
+ --trustAll
+ --no-prompt</screen>
+
+ <para>Wait a while for users to authenticate again (or test it yourself) so
+ that OpenDJ writes the timestamps. The following search then returns users
+ who have authenticated in the last three months (13 weeks) after you
+ configured OpenDJ to keep the last login timestamps.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ "(lastLoginTime:1.3.6.1.4.1.26027.1.4.6:=13w)" mail
+dn: uid=bjensen,ou=People,dc=example,dc=com
+mail: bjensen@example.com
+
+dn: uid=kvaughan,ou=People,dc=example,dc=com
+mail: kvaughan@example.com</screen>
+ </example>
</section>
-
+
+
<section xml:id="compare-ldap">
<title>Comparing Attribute Values</title>
<indexterm><primary>Comparing attribute values</primary></indexterm>
--
Gitblit v1.10.0