OpenDJ: Changing server certificates

The default validity period for OpenDJ self-signed certificates used to be 730 days. Those of you who generated keys & self-signed certificates a couple of years ago could have certificates that will expire soon.

There’s a new chapter in the OpenDJ Administration Guide that covers Changing Server Certificates, including not only replacing the keys for regular connection handlers, but also generating new keys & self-signed certs used to protect replication traffic.

You will find the Configuring Servers For Client Application Access chapter has been beefed up with more examples of manipulating certificates using the Java keytool command, including CA-signed certificates. Plus, the Performing LDAP Operations chapter now also demonstrates Authenticating Using a Certificate, showing the steps to have an application, for example, authenticate to OpenDJ without a user name and password.

Docs: .example vs. .com

In OpenAM docs we often need to differentiate between second-level DNS domains. When writing about federation, for example, we need to distinguish among providers. In the real world, many providers use .com as the top-level domain and their brand as the second level domain. Hence we have ended up accidentally squatting on other people’s property, like idp.com or sp.com.

Read them again: idp.com and sp.com.

If they look like Internet domain names, that is because they are.

Now read these: idp.example and sp.example.

Hesitation? Actually these are the “correct” examples for use in documentation.

The string “.com” is self-evidently obvious as a top-level domain even to people who cannot say what DNS stands for or what it does. So adding something in front of .com makes it instantly recognizable: “Oh, that’s an Internet name.”

Unfortunately, we ought not use .com in documentation where we need to differentiate by second-level domain. Almost all *.com domains can belong to somebody else.

As mentioned, there is a workaround. RFC 2606 sets aside .example, .example.com, .example.net, .example.org for use in documentation. It also sets aside others like .test.

".test" is recommended for use in testing of current or new DNS
related code.

Similar story with .invalid and .localhost. These are reserved but not suited to most documentation.

Our docs do use .example.com, .example.net, .example.org. But those hide the differentiation in the top-level domain instead of where we want it in this case, which is the second level. We would have idp.example.net and sp.example.com, which is technically correct but harder to understand when reading.

The reserved top-level .example looks weird to anybody who has not read RFC 2606. I have read RFC 2606 and it still looks weird to me. idp.example in the doc is technically correct. The trade off is that readers have to slow down and think, “What the heck is idp.example? (Quick search…) Oh, these writers have read RFC 2606, which says .example is like .com, except that it’s reserved as community property so that it can be used in documentation. Okay, what was I thinking about before I got stuck on that…?”

Even though the reserved names in RFC 2606 can violate the rule of least surprise, as long as we are consistent in applying RFC 2606, then .example might be the best choice in the long term.

First, using .example is the best correct workaround that we know of at this point.

Second, using .example might actually encourage people who like the challenge of getting their heads around reasonably complex topics such as access management federation. After one stumbles on .example once or twice, one looks it up and learns what is “correct.” This once again confirms the reader’s status as a power user who knows sundry Internet arcana, turning the stumbling block into its own reward.

Third, it also makes us writers look like we know what we are writing about. We even pay attention to details like RFC 2606. (On the other hand, now that we pay attention to RFC 2606, we probably should be extra careful about the really important details, too.)

forgerock-doc-maven-plugin 1.1.0 released

It’s always satisfying to release something, even if you’re just scratching your own itch. Today the ForgeRock doc build plugin reached 1.1.0.

As mentioned on the mailing list, “This release fixes a few issues, and includes a number of improvements that have already been visible in the documentation for a while now.” Basically, it’s something stable before we embark on 2.0.0, which I hope will reach release in the fall next year, and include many significant improvements to doc layout and usability.

ForgeRock welcomes Mike Jang

Welcome to Mike Jang who joined the ForgeRock documentation team this past Monday. Glad to have you with us, Mike!

If you have studied for a Linux certification exam, you might have done so with one of Mike’s books. He likes learning new software, having taught himself SELinux, iptables-based firewalls, LDAP, Kerberos, repository-based package management tools, virtualization and more, with ForgeRock access management software next on his list. Mike has done both technical writing and also teaching. As you might have noticed, he started contributing to the OpenAM mailing list before joining ForgeRock.

Mike’s main focus at ForgeRock will be access management documentation for the OpenAM and OpenIG projects. It’s great to have another skilled writer, and especially good for the community to have someone so well-versed in what system administrators really need to know.

Get out the vote

You have perhaps voted in one of the polls down the right side of the page.

Click the View Results links in the polls below to see details:

• Tomcat wins the OpenAM container poll.
  
• A third of voters reads man pages daily.
  
• 3/10 of voters say the docs are whatever they turn up searching the web. But almost 2/10 call for printed manuals.
  

You can also vote for what you want to know about OpenAM. See Peter’s blog for a link to the form.

JCite and DocBook Together

Peter Arrenbrecht‘s JCite – Java Source Code Citation System – looks like something we could use to keep our DocBook-based developer documentation in sync with Java examples.

One of JCite’s strengths is in generating HTML content with <span>s for syntax highlighting. Yet, JCite also supports “plain” citations, pulling in content without extra markup, instead only escaping special characters like <, >, and &.

I tried it with a small sample DocBook <chapter>, chap-jcite.xml. That chapter uses JCite to cite Java code from a Test class. (Sorry, no, I haven’t yet worked out how to plug JCite for DocBook into WordPress.)

 <para>The following example cites an entire Java class.</para>

 <programlisting language="java"
 >[jcp:org.forgerock.doc.jcite.test.Test]</programlisting>

 <para>The following example cites a single Java method.</para>

 <programlisting language="java"
 >[jcp:org.forgerock.doc.jcite.test.Test:--- mainMethod]</programlisting>

When the file is processed, the output contains cited code from Test.java

 <programlisting language="java"
 >package org.forgerock.doc.jcite.test;

/**
 * Test class for trying JCite.
 */
public final class Test {
    /**
     * Print a message, then print args one per line.
     * @param args Program arguments.
     */
  // --- mainMethod
    public static void main(final String[] args) {
        System.out.println(&quot;This is just a test.&quot;);
        for (String arg : args) {
            System.out.println(&quot;\t&quot; + arg);
        }
    }
  // --- mainMethod
}</programlisting>

 <para>The following example cites a single Java method.</para>

 <programlisting language="java"
 >public static void main(final String[] args) {
    System.out.println(&quot;This is just a test.&quot;);
    for (String arg : args) {
        System.out.println(&quot;\t&quot; + arg);
    }
}</programlisting>

Pretty nifty. The ForgeRock doc build plugin gets syntax highlighting elsewhere, so in principle this should work for ForgeRock docs.

Where’s the JCite Maven plugin?

Maven doc plugin: Single chapter output

As Lana mentioned to me the other day, if you make small changes to core docs, it can be painful to wait for the entire documentation set to generate just to see how your changes look in HTML or PDF for example. The fix for DOCS-29 lets you generate output for a single format. You can use the documentSrcName parameter to restrict what gets built to a single file, such as an individual chapter.

The following command generates PDF only for a single chapter of the forgerock-doc-maven-plugin-test project.

$ mvn -DdocumentSrcName=chap-one.xml -Dinclude=pdf clean pre-site

Find the pre-site output under target/docbkx/.

$ ls target/docbkx/pdf/*.pdf 
target/docbkx/pdf/ForgeRock-Bogus-Guide.pdf

Caveats:

• If you defined <excludes>, then you cannot use <include> in the same configuration.
• If you have multiple chapters with the same name, this might not work as expected. My guess is the last one wins.
• The documentSrcName must correspond to a file. You cannot currently generate output for a part of a file, nor for several arbitrary files.

OpenDJ: Finding configuration documentation

The Admin Guide comes right out and says it:

In addition to the dsconfig reference that covers subcommands, the Configuration Reference covers the properties you can set using the dsconfig command.

Easier written than fully understood.

OpenDJ has many configuration options, only a few of which are accessible through the OpenDJ control panel.* Most configuration procedures involve use of the dsconfig command.

The dsconfig command has many options. Starting the command interactively with OpenDJ 2.5.0-EXPRESS1 shows a menu that nearly scrolls off a 80×24 terminal:

    1)   Access Control Handler               21)  Log Publisher
    2)   Access Log Filtering Criteria        22)  Log Retention Policy
    3)   Account Status Notification Handler  23)  Log Rotation Policy
    4)   Administration Connector             24)  Matching Rule
    5)   Alert Handler                        25)  Monitor Provider
    6)   Attribute Syntax                     26)  Password Generator
    7)   Backend                              27)  Password Policy
    8)   Certificate Mapper                   28)  Password Storage Scheme
    9)   Connection Handler                   29)  Password Validator
    10)  Crypto Manager                       30)  Plugin
    11)  Debug Target                         31)  Plugin Root
    12)  Entry Cache                          32)  Replication Domain
    13)  Extended Operation Handler           33)  Replication Server
    14)  External Changelog Domain            34)  Root DN
    15)  Global Configuration                 35)  Root DSE Backend
    16)  Group Implementation                 36)  SASL Mechanism Handler
    17)  Identity Mapper                      37)  Synchronization Provider
    18)  Key Manager Provider                 38)  Trust Manager Provider
    19)  Local DB Index                       39)  Virtual Attribute
    20)  Local DB VLV Index                   40)  Work Queue

    q)   quit

Enter choice:

Suppose you arrive at this menu thinking, “I want to lock users out for 5 minutes if they get their password wrong 3 times in a row.” You scan the list of options. You quit and try `/path/to/OpenDJ/bin/dsconfig --help-all | grep -i lockout`, but come up empty. You ask a colleague who has no idea. You almost search for “opendj account lockout” and find it in the Admin Guide, but then you decide that you do not want to have to rely on finding something in the Admin Guide. Surely the Admin Guide will never cover everything you plan to do with OpenDJ. So you want to figure out how to use the reference documentation.

As the Admin Guide states, there are two parts** to the configuration reference documentation:

• The dsconfig reference
  This covers dsconfig and all its many subcommands and options. Everything is also available through the dsconfig help built into the command, the advantage of the reference being that you can search through everything at once.
• The OpenDJ configuration reference
  This covers all the individual configuration properties you can set with dsconfig, and also shows you how the configuration properties are attached to configuration objects, plus the configuration object inheritance. You need to know inheritance because dsconfig is arranged by kinds of objects. Some objects are abstract parents of the configuration objects you create.

You open the OpenDJ configuration reference to the default page, where the left frame shows Inheritance, and you search for “account”. This turns up account status notification handler configuration objects. You search for “lockout”. Nothing. You think, “Okay, where’s the alphabetical list of everything I can configure?” You find it under the Properties tab in the left frame, and you search again for “lockout”. Now you are getting somewhere:

lockout-duration [ Password Policy ]

lockout-failure-count [ Password Policy ]

lockout-failure-expiration-interval [ Password Policy ]

lockout-failure-count and lockout-duration look promising. Perhaps you can set lockout-failure-count to 3 and lockout-duration to 5m. There’s also a lockout-failure-expiration-interval that might be useful to avoid locking users out if consecutive failures happened over hours or days rather than all in a row. You notice that these properties are configured on Password Policy configuration objects.

You could click the links and read more, but instead you go back to the interactive dsconfig session, and you choose 27)  Password Policy. From there, the menu-driven interaction makes it relatively easy to discover and then change the settings.

And thus you are on your way to becoming a dsconfig guru. (After you get the hang of it, read about the options --advanced, and especially --commandFilePath, and --batchFilePath in the dsconfig command reference so that you can really do everything including generate scripts from your interactive sessions that you can use again later for tasks you repeat.)

---

* It’s not quite strictly true that you cannot configure more of OpenDJ through the control panel. If you Manage Entries > Base DN > cn=config, you can hack the config. Realize that you are accessing a private interface in that case, however. What you are doing is similar to editing OpenDJ/config/config.ldif directly. Mistakes can break your server.

** Someday, there might be one part. See OPENDJ-386.

ForgeRock welcomes Lana Frost

Welcome to Lana Frost who joined the ForgeRock documentation team Monday. Glad you decided to work for ForgeRock, Lana.

Lana has worked as Lead Writer at Sun Microsystems on the Directory Services team, and more recently at Oracle. While helping other writers meet their deadlines and keeping the projects on track, she also wrote a big share of the directory documentation herself. Furthermore, Lana was instrumental in setting up the rigorous documentation review process that first lifted the quality of the directory documentation, and was later adopted by other middleware documentation teams.

Lana will help with OpenDJ docs at ForgeRock. Her main focus however is the leadership role for identity documentation with the OpenIDM and OpenICF projects. Good news for the ForgeRock directory and identity communities!

Docs: Folding review into the normal dev process?

Perhaps you have read the recent updates to the community development process page. In a nutshell there’s a push to doing review-then-commit rather than the other way around.

As I described earlier, we currently use a doc-specific review process to ensure technical accurate and complete core docs at the time of release. The doc review process sits alongside the standard development process, and so requires a bit of extra work in management and tracking. Also, as long as the doc review process sits outside the main development process it will not be as easy to track as the rest of the work.

Should we fold the doc review process into the normal development process?

Review-then-commit certainly promises to reduce the additional workload in tracking and managing dev review. In theory if we manage to commit content that is ready for validation testing at the same time as the code it should ease the burden on people doing testing and validation. Perhaps testers will not have to switch context back to features studied much earlier. They might even find the doc useful when working with new features.

The downsides don’t seem insurmountable. Design review, really part of product definition, still needs to be tracked separately. But once design review is done, it can result in JIRA issues that we handle like the rest of the work. For validation testing, quality assurance might prefer that writers track coverage. Or perhaps that will be part of the test plan. Either way seems fine as long as the work is not falling through any cracks. There are also a few documentation updates where IMHO review-then-commit is just overkill. Commit-then-review is no doubt the best approach when fixing typos, for example. Commit-then-review might also be best for editorial fixes and indexing, too.

So I’m tentatively guessing that although it is a significant shift from what we have done so far, folding doc review into the normal dev process will improve quality and save effort. I’ll be trying to stick closer to the standard development process starting with OpenAM 10.1.0 (and associated policy agent and OpenIG docs).

What do you think?