In part 1 of this series What do the various IDM driver object attributes represent - Part 1 I discussed some of the attributes that are found on the DirXML-Driver object when you look at it raw in the directory. In the first article I covered the following attributes:
DirXML-Policies
DirXML-NextTransformation
DirXML-ACT2
DirXML-ApplicationSchema
DirXML-ConfigManifest
DirXML-ConfigValues
DirXML-Filter
In this article I will cover the following attributes:
DirXML-DriverImage
DirXML-DriverStartOption
DirXML-DriverStorage
DirXML-DriverTraceLevel
DirXML-LogEvents
DirXML-LogLimit
DirXML-TraceFile
DirXML-TraceFileEncoding
DirXML-TraceLevel
DirXML-TraceName
DirXML-TraceSizeLimit
DirXML-DriverImage
This attribute is a stream syntax attribute. Stream attributes are stored as files in the DIB directory as standalone files, usually named by the object ID. In the olden days, Login Scripts and many of the Zenworks attributes were Stream syntax. These are for things that are known to be 'large' or perhaps indeterminately large, and thus make little sense as an attribute. In the Zenworks case, some of the attributes could get very large as files, or perhaps lists of files (hundreds or even thousands of files) could be stored.
In iManager and Designer you can change the value of this attribute. Using those UI's you can upload a picture file. You can modify this via LDAP in which case it should be a JPG (I am not sure if any other format is supported) and base 64 encoded.
DirXML-DriverStartOption
This is where the Auto, Manual, and Disabled values are stored for the driver start options. When you switch a driver to Disabled, the important thing to note is that DXevent (the event engine for Identity Manager) stops watching for events in the drivers filter. This means the TAO file (where events are cached) is not updated, and in fact is actually reset to null. (Which might be 72 bytes, but that is null enough). When you change a driver AWAY from being Disabled, make absolutely sure you watch out for the "Do Not Resync on changing from Disabled" button is checked. In iManager it only appears when you have a Disabled driver and are switching it to anything else. Designer shows it all the time, even on drivers that are not Disabled. This is important, because if you do NOT set this option, then when you change the driver from Disabled, it WILL cause a full resync of all objects in the vault to the connected system, which potentially could take hours. Or if you have enough objects, days or more. (I have seen IDM solutions with active object counts in the millions, so you can imagine how long that might take to process). You have until you actually start the driver the first time after it was disabled to try and fix this. The logic behind it is actually sound. During the interval that the driver was disabled and dxevent was not collecting events for it, any number of changes might have happened and now the two systems are very likely out of sync to some degree. This can be fairly problematic thus by triggering a resync, all objects will get back into a fully in sync state.
DirXML-DriverStorage
The driver storage attribute is an interesting one. The contents differ based on the driver shim in use, as each implements the usage of this attribute differently. I happen to have a couple of examples handy from a JDBC driver and from an Active Directory driver.
JDBC Driver DirXML-DriverStorage attribute example:
<?xml version="1.0" encoding="UTF-8"?><init-params><publisher-state><domain url-crc="2027935890"><subdomain schema-name="IDM"/></domain><schema><table naming-crc="3251335684" qualified-name="IDM.WORK_ORDER"/><table naming-crc="3251335684" qualified-name="IDM.CLIENTS"/></schema></publisher-state></init-params>
Active Directory Driver DirXML-DriverStorage attribute example:
<?xml version="1.0" encoding="UTF-8"?><init-params><publisher-state><cookie>TVNEUwMAAAAOIdkaFj3IAQAAAAAAAAAAcAAAAI s1gAAAAAAAAAAAAAAAACPrNYAAAAAAE tZI7AvppApDkmhz/o/8oBAAAAAAAAAAQAAAAAAAAAhGvXYGLG40G5r BfKDbXwfsIlAAAAAAAT61kjsC mkCkOSaHP j/yqCs1gAAAAAADTai9edE6k6X9Ly1pdqKlDchAQAAAAAA8lXu Tsd10Wbru2zyWePvV/FiQAAAAAA</cookie></publisher-state></init-params>
Basically when you cleanly stop a driver, a couple of attributes get updated. DirXML-PersistantData and DirXML-DriverStorage. I will talk about DirXML-PersistentData in a later article. (I am trying to go through these somewhat alphabetically)
This is basically some kind of bookmark, showing the driver where it last did something with the connected system. This way, when the driver restarts it will have a notion of where to pick up where it left off.
In the case of the Active Directory driver, this is a cookie that represents the last update it received from Active Directory. After all, on the engine side, we have DXevent handling events and storing them in the TAO file until the driver is restarted and replays them. On the connected system side, this attribute provides a place to store a high water mark, so the shim can resume on the Publisher channel.
Often, on the connected system the state will also be stored in a .state file. It will be in the Remote Loader directory (I assume it will be in the DIB directory if you are running the driver Local in an eDirectory instance instead of Remote via a Remote Loader) and named by the remote loader configuration file and end in .state.
The Active Directory driver stores basically the same XML you see in the attribute as it does in the state file.
The JDBC driver is a bit more interesting as it may have a state file stored as .DB file, which is the case of the Triggerless mode of the driver actually stores the timestamps of all the values of the database. This way it knows on the next poll, when it asks for the timestamps what to compare with, to decide if an row or table has been updated in the latest polling cycle.
If you happen to have samples of what other drivers store in the DirXML-DriverStorage attribute, please leave a comment of contact me, so I can update the article with the additional information.
DirXML-DriverTraceLevel
This is an area where I am unclear. I suspect this may be a hold over from earlier days of the product. There are actually a whole set of attributes that control driver tracing. This is distinct from DirXML-LogLimit, which controls just the 'events' logging that are then stored in DirXML-LogEvents. In this context, a Log event is something like the Status documents, be they success, warning, or error. This by default writes to an attribute on the driver, which is not very efficient as eDirectory is a great performer at reading, but slower at writing. But it can be set to forward these Status events to the Audit component, and to whatever is listening. That might be NSure Audit, which is deprecated. Identity Audit, Sentinel, Sentinel Log Manager, Sentinel Rapid Deploy, or in IDM 4 the Reporting module.
Some of the other related attributes are:
DirXML-TraceFile
DirXML-TraceFileEncoding
DirXML-TraceLevel
DirXML-TraceName
DirXML-TraceSizeLimit
These attributes control the DSTrace logging. Compared to 'LogEvents" this is actually useful, and one of the nicer parts of DirXML Script policy! Every thing can be traced to a log file, and then you can see step by step what happened, what worked, what failed. Learning to read this trace file can be tricky and take a fair bit of experience but it really does get easier with practice.
First off, where to find Dstrace? Well it turns out there are many places you could look and some are better than others. I detailed this in the article: The Many Faces of DSTRACE
I tried to write a guide to understanding what is going on in Dstrace to make it easier to read, so take a read and let me know if it helps. Guide to Reading DSTRACE Output from Identity Manager
However, my effort pales in comparison to Fernando Frietas' version, that is just epic in its scope and quality. If you read nothing else, I suggest you read the first article, (and the next two, but at least the first):
I recommend these to everyone learning IDM as mandatory reading. It will save you hours and hours of confusion later, as you try to troubleshoot the normal issues that arise. Fernando did an exemplary job, and I highly recommend it!
Some other articles I have written on the topic of DStrace are below:
The various attributes for Trace settings interact with each other, and what is kind of neat is they take affect live. That is, you can have a running driver, say processing a full resync, and as I described in the article above, DStrace severely degrades the engines performance. This is because the XML that we see in the DSTrace output is actually in a more efficient binary format that the engine uses in memory. As soon as you enable trace at any level that requires showing the XML, it must be serialized into a text like format which is a big performance hit.
But since the attributes are interpreted live, if you have a resync running you should turn trace down to 0 or null (delete the attribute). You can be watching with the use of say a tool like "tail -f LogFileName.log" on a Unix or Linux variant, and you will see the output stop. Then if later in the day you want to see how far along it is, using ConsoleOne or an LDAP browser, you could just edit the attribute, set it to 3, save it, and your 'tail'ed file will start spewing out trace again. In case you were not aware, using the ubiquitous 'less' command, you can start looking around your log file, and usually a capital G will jump you to the bottom of the text, even if more has been written to the file since you started your 'less' process session. Additionally, a cpaital F will turn 'less' into a 'tail -f' session, and a Ctrl-C will break you back to 'less'. This way you never really need 'tail -f' again. Just use 'less' and capital F.
I do not know if this will work for the DirXML-TraceFile, DirXML-TraceFileEncoding, DirXML-TraceName, and DirXML-TraceSizeLimit but in those cases, it really does not matter that much. That is, you do not really care to modify the name of the token used in the trace file (DirXML-TraceName) on the fly all that often. The DirXML-TraceSizeLimit is pretty obvious, the size in Megabytes to keep the log at. This is important as otherwise (if run with no value, then it implies unlimited) you could fill your disk volume pretty trivially. DirXML-TraceFile is the name of the file, which needs to be in the correct syntax for the platform eDirectory is installed upon. For example on Netware it would be a format like vol1:\logs\driver.log, for a Unix platform /var/log/novell/driver/driver.log, whereas for Windows it might be d:\logs\driver\driver.log.
I have never really used DirXML-TraceFileEncoding, but I suppose if you have non-ASCII characters and data in your system, this may become useful to properly trace some of that content.
There is an interesting interaction with the Driver Set level versions of these attributes. All these DirXML-Trace* attributes can be set at the Driver Set level as well. Like the inheritance of Global Configuration Variables (GCV) values, if it is set at the Driver Set level then it applies, until something lower level overrides it. That is, you could set the DirXML-TraceLevel on the Driver Set to 1 and then in individual drivers set it to 3 as needed.
I have not tried to see if the driver set level attributes take affect live or not. Again, it is usually not that crucial except in the case of the trace level itself.
There are additional levels of trace, that other attributes control:
There are DirXML-LogEvents and DirXML-LogLimit that control a different case of logging as opposed to trace.
There is also DirXML-XSLTraceLevel which is not available at the driver level, only at the driver set level, and is something I have not played around with much. One of the pains in working in XSLT as opposed to DirXML Script Policy is the difficulty in debugging. With DSTrace it is very easy to edit a rule, test it either live or with Simulator (you can read more about using Simulator in the article: Using Simulator in Designer ), see a mistake in DSTrace, exactly where it happened, and then fix it, try again, see that it either worked or failed for a different reason and iterate through to a solution.
With the XSLT approach you have to put your own debug logging inline at each step, narrowing it down until you figure it. I guess I am just spoiled and really enjoy the DirXML Script approach since it makes things so much easier. Thus I spawned this article on the topic of what do we really need XSLT for? I concede most things COULD be done in XSLT or in DirXML Script, but they are usually easier to write, managed, and debug in DirXML Script: Open Call: What Can You Do in XSLT that You Cannot Do in DirXML Script?
Well that's about it for this article. Stay tuned for more as I work through some of the other schema attributes of the DirXML Driver and DirXML Driver Set objects!
Support
Documentation
Learning Services
Partner Programs