OpenDJ: Finding configuration documentation

OpenDJ Community LogoThe 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.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s