Docbkx-tools: section numbering

docbkx-tools logo Jamie mentioned yesterday that we were missing section numbering for the docs.

Chapters are numbered by default. Not so for sections. So we had something like the following.

Chapter 1. My First Chapter
My First Section
My First Subsection
My Second Subsection
My Second Section
Chapter 2. My Second Chapter

What we wanted was something more like the following.

Chapter 1. My First Chapter
1.1. My First Section
1.1.1. My First Subsection
1.1.2. My Second Subsection
1.2. My Second Section
Chapter 2. My Second Chapter

By setting two stylesheet parameters in the pom.xml global configuration section invoking the docbkx-tools plugin, you get the latter in the generated documents.


I learned the parameter names from the DocBook XSL Stylesheets: Reference Documentation, by the way. Just translate the DocBook stylesheet parameter names with dots, like section.label.includes.component.label, to camelCase names, like sectionLabelIncludesComponentLabel, for the docbkx-tools configuration elements.

For an example, see the pom.xml for OpenDJ.

OpenDJ: Editing LDIF by hand

OpenDJ Community Logo Sometimes the fastest way to get something done involves editing LDIF as text.

If you are not used to working with LDIF in a text editor, OpenDJ Control Panel is a good place to start. Find the entry you want to change in the Manage Entries window, and then select View > LDIF View. When you save changes, OpenDJ Control Panel lets you know if you made a mistake.

LDIF edit error shown in Control Panel

You still need to decipher from the message that lines starting with a string and not white space are interpreted as attribute names, but at least the Control Panel let’s you try again right away. Forgetting to put a space at the start of a continuation line is a common error, so here it is again, command line version.

$ cat broken.ldif
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
replace: description
description: This description continues on the next line,
but the continuation does not start with a space.

$ ldapmodify -p 1389 -D "cn=Directory Manager" -w password -f broken.ldif
Error at or near line 1 in LDIF file /path/to/broken.ldif:
org.opends.server.util.LDIFException: Unable to parse LDIF entry starting at
line 1 because the line "but the continuation does not start with a space."
does not include an attribute name

Another error that can happen comes from accidentally adding white space at the end of an attribute value. Let’s see what happens when you do that.

$ cat extra-space.ldif
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
replace: description
description: This description ends with an extra space. 

$ ldapmodify -p 1389 -D "cn=Directory Manager" -w password -f extra-space.ldif
Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
MODIFY operation successful for DN uid=bjensen,ou=People,dc=example,dc=com
$ ldapsearch -p 1389 -b dc=example,dc=com uid=bjensen description
dn: uid=bjensen,ou=People,dc=example,dc=com
description:: VGhpcyBkZXNjcmlwdGlvbiBlbmRzIHdpdGggYW4gZXh0cmEgc3BhY2UuIA==

Notice that the directory happily accepts your mistake… and base64 encodes the result. So the value still shows up as expected when you decode the result, but it can be a surprise if a script somewhere is expecting the value you meant to use without having to base64 decode the value:

$ base64 decode -d VGhpcyBkZXNjcmlwdGlvbiBlbmRzIHdpdGggYW4gZXh0cmEgc3BhY2UuIA==
This description ends with an extra space.

Hope these help next time you have to edit some LDIF.

OpenDJ: Proxy auth

OpenDJ Community Logo The question of doing proxy authorization came up on the OpenDJ mailing list. Proxy authorization lets you connect to a directory server as one user, yet then perform operations as another user. You might, for example, have an application that connects as cn=My App, but then uses uid=kvaughan when performing an operation. There are two versions of proxy auth, with the latest being defined by RFC 4370. That RFC identifies the proxied authorization control OID, 2.16.840.1.113730.3.4.18.

Proxy auth relies on both OpenDJ privileges and also access control, so you need to set both to allow proxy auth to work. Privileges and access control are addressed in the same Admin Guide chapter.

For example, suppose you have an application with DN cn=My App,ou=Apps,dc=example,dc=com that should be allowed to use the proxy auth control.  My App will use the control when directory admin Kirsten Vaughan connects through My App to update the description on Babs Jensen’s entry. In order for this to work, My App needs access to use the proxy auth control in requests, needs the privilege to use proxy auth, and also needs access to use proxy auth on the data affected.

For access to use the proxy auth control, by default OpenDJ lets authenticated users use the control.

$ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager"
> -w password get-access-control-handler-prop --property global-aci
(targetcontrol=" || ||
           : || 1.2.840.113556.1.4.319 || 1.2.826.0.1.3344810.2.3 ||
           : 2.16.840.1.113730.3.4.18 || 2.16.840.1.113730.3.4.9 ||
           : 1.2.840.113556.1.4.473 ||") (version
           : 3.0; acl "Authenticated users control access"; allow(read)
           : userdn="ldap:///all";)

For the privilege to use proxy auth, add the relevant attribute to My App’s entry.

$ ldapmodify -p 1389 -D "cn=Directory Manager" -w password
dn: cn=My App,ou=Apps,dc=example,dc=com
changetype: modify
add: ds-privilege-name
ds-privilege-name: proxied-auth

Processing MODIFY request for cn=My App,ou=Apps,dc=example,dc=com
MODIFY operation successful for DN cn=My App,ou=Apps,dc=example,dc=com

For proxy auth access to the data, set up an ACI that explicitly allows proxy permission.

$ ldapmodify -p 1389 -D "cn=Directory Manager" -w password
dn: dc=example,dc=com
changetype: modify
add: aci
aci: (target="ldap:///dc=example,dc=com") (targetattr ="*
 ")(version 3.0; acl "Allow apps proxy auth"; allow(all, proxy
 )(userdn = "ldap:///cn=*,ou=Apps,dc=example,dc=com");)                 

Processing MODIFY request for dc=example,dc=com
MODIFY operation successful for DN dc=example,dc=com

At this point you can test proxied authorization.

$ ldapmodify -p 1389 -D "cn=My App,ou=Apps,dc=example,dc=com" -w password \
> -Y "dn:uid=kvaughan,ou=People,dc=example,dc=com"
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
replace: description
description: Changed through proxied auth

Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
MODIFY operation successful for DN uid=bjensen,ou=People,dc=example,dc=com

In the access log, you see something like the following (lines folded).

[28/Jun/2011:10:18:05 +0200] CONNECT conn=9 from=
 to= protocol=LDAP
[28/Jun/2011:10:18:05 +0200] BIND REQ conn=9 op=0 msgID=1 version=3
 type=SIMPLE dn="cn=My App,ou=Apps,dc=example,dc=com"
[28/Jun/2011:10:18:05 +0200] BIND RES conn=9 op=0 msgID=1 result=0
 authDN="cn=My App,ou=Apps,dc=example,dc=com" etime=1
[28/Jun/2011:10:18:55 +0200] MODIFY REQ conn=9 op=1 msgID=2
[28/Jun/2011:10:18:55 +0200] MODIFY RES conn=9 op=1 msgID=2 result=0
 authzDN="uid=kvaughan,ou=People,dc=example,dc=com" etime=329
[28/Jun/2011:10:19:00 +0200] UNBIND REQ conn=9 op=2 msgID=3
[28/Jun/2011:10:19:00 +0200] DISCONNECT conn=9 reason="Client Unbind"

Good luck setting up your own proxy auth.

OpenDJ: Admin Guide first draft

OpenDJ community logo Glad to reach a milestone this afternoon of having draft chapters for what I want to do in the Admin Guide for 2.5, except for Pass-Through Authentication (waiting for the implementation to finish).

I am looking for reviewers to help spot errors, missing information, incomprehensible passages, etc.

If you would like to sign up as a reviewer, leave me a comment, and sign up through the OpenDJ 2.5 Documentation Review Dashboard Wiki page. I’m sure Matt won’t mind if you take one of his spots. 🙂

OpenDJ: Config reference posted

OpenDJ community logo You may have noticed we have more and more draft chapters for the Admin Guide, but the OpenDJ Configuration Refererence was missing until today. At the end of May, Matt added a Maven module for the current builds of the server. Yesterday, Ludo fixed a number of the files that the config ref depends upon. Today, I made some changes to take advantage of both of those developments so we could post the config ref on the OpenDJ community site.

The Config Reference is what you need to configure the server from the command line when the Admin Guide examples do not match your case exactly. After you get auto-completion working for dsconfig, you notice that dsconfig has LOTS of subcommands with even more properties to get/set. All those properties are doc’d in the config ref.

OpenDJ: More fun with certs

OpenDJ Community Logo In looking at writing doc on how to move OpenDJ servers, the tricky bit looked like switching certificates after changing hosts. As the server host name is embedded in a certificate, if you move a server you want to replace certificates, at least the admin-cert in the admin-keystore (for private keys) and in the admin-truststore. You can replace the admin-cert with another self-signed cert.

  1. Remove the certificate to replace from the keystore and from the truststore.
    $ keytool -delete -alias admin-cert -keystore admin-keystore \
    > -storepass `cat`
    $ keytool -delete -alias admin-cert -keystore admin-truststore \
    > -storepass `cat`
  2. Generate the private key, storing it in the keystore.
    $ keytool -genkey -alias admin-cert -keyalg RSA \
    > -dname "CN=hostname, O=Administration Connector Self-Signed Certificate" \
    > -keystore admin-keystore -storepass `cat` \
    > -keypass `cat`
  3. Self-sign what you generated.
    $ keytool -selfcert -alias admin-cert -keystore admin-keystore \
    > -storepass `cat`
  4. Export the certificate from the keystore.
    $ keytool -export -alias admin-cert -keystore admin-keystore \
    > -storepass `cat` -file admin-cert.crt
    Certificate stored in file <admin-cert.crt>
  5. Import the certificate into the truststore.
    $ keytool -import -alias admin-cert -keystore admin-truststore \
    > -storepass `cat` -file admin-cert.crt
    Owner: CN=hostname, O=Administration Connector Self-Signed Certificate
    Issuer: CN=hostname, O=Administration Connector Self-Signed Certificate
    Serial number: 4e0321c6
    Valid from: Thu Jun 23 13:21:42 CEST 2011 until: Wed Sep 21 13:21:42 CEST 2011
    Certificate fingerprints:
      MD5:  5C:4B:CC:9A:37:E2:71:BD:C4:86:8E:FC:D4:37:39:57
      SHA1: 70:D0:36:0D:EB:0D:AC:45:6D:A4:EF:8A:8E:CB:C7:04:7D:3A:EE:6E
      Signature algorithm name: SHA1withRSA
      Version: 3
    Trust this certificate? [no]:  yes
    Certificate was added to keystore

Going to add this in the right place in the Admin Guide pretty soon. You might also want to do something like this if your self-signed cert gets so old that it is no longer valid.

OpenDJ: Mail Users About Account Status

OpenDJ community logo You can mail users about their account status. I found this while documenting the monitoring interfaces of OpenDJ today.

For extra credit, you can guess how to set up password policy by preferred language, and then configuring a handler per preferred language so the mails for non-English speakers do not have to get sent through

  1. Identify the SMTP server to which OpenDJ sends messages.
    $ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
    > set-global-configuration-prop --set -X -n
  2. Set up OpenDJ to be able to mail users about account status.
    $ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
    > set-account-status-notification-handler-prop \
    > --handler-name "SMTP Handler" --set enabled:true \
    > --set email-address-attribute-type:mail -X -n

    You can also configure the message-subject and message-template-file properties. Try interactive mode if you plan to do so.

    You find templates for messages by default under the config/messages directory. You can edit the templates to suit your purposes.

  3. Adjust applicable password policies to use the account status notification handler you configured.
    $ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
    > set-password-policy-prop --policy-name "Default Password Policy" \
    > --set account-status-notification-handler:"SMTP Handler" -X -n

I suppose this belongs in the Admin Guide chapter on password policy.

OpenDJ: CoS with Collective Attributes

OpenDJ Community Logo This morning found me scratching my head for a reasonable example for the OpenDJ admin guide chapter on virtual and collective attributes. I ended up adding some more content to the Example.ldif file I have been using, including some comments at the top about how to update the schema. 😦

I write 😦 not because updating directory schema is difficult… in fact its really easy with OpenDJ. 🙂 But it makes the example more complicated.

Trouble is, who wants to generate postal address or zip code based on location? Or add a manager hierarchy to the sample data? I wanted to do this:

This example positions collective attributes that depend on the classOfService attribute values.

  • For entries with classOfService: bronze, mailQuota is set to 1 GB, and diskQuota is set to 10 GB.
  • For entries with classOfService: silver, mailQuota is set to 5 GB, and diskQuota is set to 50 GB.
  • For entries with classOfService: gold, mailQuota is set to 10 GB, and diskQuota is set to 100 GB.

Collective attributes make that pretty easy as shown in the doc. But you still need to add the attributes and an object class to allow them.

OpenDJ: Today’s webinar

Today Ludo is leading two webinars covering OpenDJ for ForgeRock partners, and I am sitting in with him. Ludo says he will post presentation materials after the second webinar later today.

Let me post what I have here in between the two sessions. First, let me say thank you to those of you participating. Also, let me reiterate what I have to say about documentation.

  1. OpenDJ draft core documentation is on its way to becoming complete. Again, core docs are those that will run the review gauntlet. We intend for core docs to be what the community considers the doc for a particular release, covering how to use all features, aiming for full technical accuracy and completeness. Core doc sources sit in the code repository alongside the rest of the software. They have a Creative Commons license. If you want to help out as a core doc author, check the guide on the wiki.
  2. OpenDJ Wiki pages are there for community sharing as well. You can edit the OpenDJ Wiki. Sign up is right there when you first login. The Wiki is an easy place to post information. There’s even a WYSIWYG editor to make it a snap to add or change content. The primary difference between the core docs and the Wiki is that the Wiki can change at any time, and pages there do not necessarily undergo review. Like the core docs, Wiki pages also have a Creative Commons license.
  3. On the developer Wiki, you will find a page with example outlines for providing white papers or case studies. White papers and case studies lie outside the core docs, instead covering topics like getting OpenDJ to work with other software, or providing a particular solution involving OpenDJ. The idea is for you, partners, to be able to advertise your expertise, showing off what you know how to do. You might choose to publish your white papers and case studies elsewhere, and perhaps not originally in English. We would like to be able at least to link to the work you are doing, to get the word out to potential customers that you are available to help them with OpenDJ.

OpenDJ 2.4.3 released

OpenDJ logo OpenDJ 2.4.3 has been released. OpenDJ 2.4.3 is an update release that fixes a number of issues, including problems found in the external change log and the bundled JE version.

To perform an evaluation install if you already have Sun Java 6 on your system, try the Java WebStart version. Some links:

You are welcome to join the community, and also to sign up for the mailing list.