Extending and Troubleshooting Directory Services

Contents:

Augmented Records
Enabling DirectoryService Debug logging
Kerberos configuration
Active Directory Plugin
Kerberos client issues in multi-domain forests
Binding with dsconfigad

Augmented Records

Best Practices

On the Open Directory server: bind to Active Directory first, then promote server to an Open Directory Master. After binding to AD, kerberize services:

sudo dsconfigad -enablesso

On the client machines: Clients need to be bound to both AD and OD.  Clients already bound to OD will need a restart of DirectoryService or reboot to see augmented records:

sudo killall DirectoryService

Augmented Record configuration and DirectoryService records

Augment Record storage  All augmented records and augment configuration records are stored on the OD master.  Configuration is stored in the "augmentconfig" record in the Config container in Open Directory.  This contains information about the Augment Node, (ie, the node storing the augment info) the Augmented Node (ie. the "foreign node") and what attributes can be augmented for different record types.

Content of an augment config record:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Augment Attribute List</key>
    <dict>
        <key>dsRecTypeStandard:Users</key>
        <array>
            <string>dsAttrTypeStandard:ServicesLocator</string>
</array>
    </dict>
    <key>Augment Directory Node Name</key>
    <string>/LDAPv3/frazzle.ets.apple.com</string>
    <key>Augment Search</key>
    <true/>
    <key>Augmented Directory Node Name</key>
    <string>/Active Directory/All Domains</string>
</dict>
</plist>

Augment Data is stored in the Open Directory node under the Augments container.  The format for the record name is RecordType:RecordName.  (ie. Users:nicole)

Example content of an augment record.  The augmented attribute in this example is is ServicesLocator.

/LDAPv3/127.0.0.1/Augments > read Users:nicole/
dsAttrTypeNative:apple-generateduid: 97E56974-B7F5-482A-97C1-148CFE692FB0
dsAttrTypeNative:apple-serviceslocator: 447C3544-B1E9-49FD-BFD0-DD8A6C3947A4:65AABBDA-6F5C-48F6-A3C7-522983ABEA55:calendar
dsAttrTypeNative:cn:
 Nicole A.. Jacque
dsAttrTypeNative:gidNumber: 20
dsAttrTypeNative:homeDirectory: /var/empty
dsAttrTypeNative:loginShell: /usr/bin/false
dsAttrTypeNative:objectClass: apple-augment extensibleObject top
dsAttrTypeNative:uid: Users:nicole
dsAttrTypeNative:uidNumber: 400910708
AppleMetaNodeLocation: /LDAPv3/127.0.0.1
GeneratedUID: 97E56974-B7F5-482A-97C1-148CFE692FB0
NFSHomeDirectory: /var/empty
PasswordPlus: ********
PrimaryGroupID: 20
RealName:
 Nicole A.. Jacque
RecordName: Users:nicole
RecordType: dsRecTypeStandard:Augments
ServicesLocator: 447C3544-B1E9-49FD-BFD0-DD8A6C3947A4:65AABBDA-6F5C-48F6-A3C7-522983ABEA55:calendar
UniqueID: 400910708
UserShell: /usr/bin/false

Augmentation Example: Augmenting the Active Directory user home directory

This example demonstrates augmenting an Active Directory user with an altername home directory storage location.  This would allow an alternate home directory storage location other than what is provided in the UNC path in the AD record.

Step 1: Set up Magic Triangle config 

Step 2: Create mount record for home directory share in Open Directory

Step 3: In the AD plugin on both servers and clients, disable "Use UNC path from Active Directory to derive network home location" (dsconfigad -useuncpath disable) 

Step 4: Modify augmentconfig to add the Home Directory Attributes to the allowed list of augmented attributes:

 In inspector, find the augmentconfig record (contained in the “Config” container) and edit the XMLPlist attribute, to add the following attributes to the list of Augmented attributes for Users: dsAttrTypeStandard:HomeDirectory and dsAttrTypeStandard:NFSHomeDirectory i.e.:

<key>Augment Attribute List</key>

    <dict>

        <key>dsRecTypeStandard:Users</key>

        <array>

            <string>dsAttrTypeStandard:ServicesLocator</string>

              <string>dsAttrTypeStandard:HomeDirectory</string>

            <string>dsAttrTypeStandard:NFSHomeDirectory</string>

Step 5: Augment a user in WGM:

Using the WGM inspector or dscl, add the dsAttrTypeNative:apple-user-homeurl (HomeDirectory) and dsAttrTypeNative:homeDirectory (NFSHomeDirectory) attributes to the augment record in the Augment container.

The content of apple-user-homeurl should be: <home_dir><url>smb://yourserver.domain.com/HomeShare</url><path>username</path></home_dir>

The content of homeDirectory should be: /Network/Servers/yourserver.domain.com/HomeShare/username

Remember that if the volume containing the home directories is not the boot volume, you need to include "/Volumes" in the path, i.e.: /Network/Servers/yourserver.domain.com/Volumes/HomeShare/username

Enabling DirectoryService Debug logging

Manually turn logging on/off:

sudo killall -USR1 DirectoryService

Start debugging automatically at startup:

touch /Library/Preferences/DirectoryService/.DSLogDebugAtStart

Logs file:

/Library/Logs/DirectoryService/DirectoryService.debug.log

Leopard now has configurable debug levels, ranging from 0-7.  Level 0 is off, level 7 logs all debug levels.  The default level when turning on debugging is 5.  This value is saved in /Library/Preferences/DirectoryService/DirectoryServiceDebug.plist.  You can use the defaults command to read and set these values:

sudo defaults read /Library/Preferences/DirectoryService/DirectoryServiceDebug "Debug Logging Priority Level"

sudo defaults write /Library/Preferences/DirectoryService/DirectoryServiceDebug "Debug Logging Priority Level" -int 2

Kerberos configuration

-non realm-specific info stored in /Library/Preferences/edu.mit.Kerberos

-realm-specifc info stored in Config container as Kerberos:YOUR.REALM.COM records

-dscl command to get all records in /Config:

dscl . -readall Config

Active Directory Plugin

New dsconfigad options:

dsconfigad -packetsign <allow|disable|require>

dsconfigad -packetencrypt <allow|disable|require>

dsconfigad -passinterval <num days>

dsconfigad -namespace  <domain | forest>

AD config files in Leopard:

Kerberos client issues in multi-domain forests

if DS has not contacted the domain, there may not be a configuration for that domain in dslocal. Check kerberos records in dslocal (dscl . -readall Config). If there is no record for the domain you are trying to access, DS has not contacted it yet.

Workaround: After binding, edit /Library/Preferences/edu.mit.Kerberos and change dns_fallback = no to dns_fallback = yes Also remove the "# autogenerated" and "# generation_id" lines so that the file is not overwritten.

If you have a disjoint AD domain, i.e. your DNS domain is foo.apple.com and your kerberos realm is BAR.APPLE.COM, you may need to add a mapping to the kerberos config so that the kerberos client realizes that the two are related.

Workaround: After binding, edit /Library/Preferences/edu.mit.Kerberos and in the [domain_realm] section, add a line mapping your DNS domain to your kerberos realm:

.foo.apple.com = BAR.APPLE.COM

Binding with dsconfigad

Two common mistakes people make are not enabling the AD plugin, and not adding AD to the DirectoryService search path. Here are script examples for doing each:

#enable AD plugin

    echo $localpass | sudo -S defaults write /Library/Preferences/DirectoryService/DirectoryService "Active Directory" Active

    echo $localpass | sudo -S killall DirectoryService

    echo $localpass | sudo -S plutil -convert xml1 /Library/Preferences/DirectoryService/DirectoryService.plist

#Add AD to the search path

dscl -u $localuser -P $localpass /Search -append / dsAttrTypeStandard:CSPSearchPath "/Active Directory/All Domains"

dscl -u $localuser -P $localpass /Search -create / dsAttrTypeStandard:SearchPolicy CSPSearchPath