The Directory Utility is a Java application you can use to manage user, group, or session configuration information stored either in Host On-Demand or in an LDAP server. The Directory Utility enables you to add or update large numbers of users, groups, or sessions from an ASCII file, instead of individually through the Administration client. For example, you can use the utility to:
The Directory Utility uses an ASCII file that defines all groups, users, and sessions. The text file needs to be in XML format, with a .xml extension.
| Running the Directory Utility | |
| Using the Directory Utility GUI | |
| XML file format / element descriptions | |
| XML file example | |
| Searching with the List function | |
| Using output of the List function |
The Directory Utility can be run using either a graphical user interface or a command line interface.
To start the graphical user interface ...
In the Directory Utility graphical user interface enter the following fields as appropriate:
This option is ignored for the add, delete, and update actions in the input XML file.
On Windows systems the command or script file to run the Directory Utility and sample file are located in the C:\Program Files\IBM\HostOnDemand\lib\samples\DirUtil directory. The command file is called DirUtil.cmd and the sample text file is called sample.xml. The command or script file for other operating systems and the sample text file are located in the hostondemand\lib\samples\DirUtilCommandFiles directory. The sample text file is called Sample.xml. The command or script files are called:
To run the Directory Utility, type the following at the command line:
 The order of the parameters is important. |
| DirUtil-xxx filename.xml admin password [hostname] [port] [CO |
| The Host On-Demand Service Manager must be running on the Host On-Demand server specified by hostname in order for the Directory Utility to update Host On-Demand or LDAP configuration information. |
For example, on AIX you could run:
DirUtil-AIX file.xml admin password myhostname 8999 CON
The Directory Utility GUI is the GUI interface for the command line application. You can use it to manage users, groups, or the information of session configurations that is stored either in Host On-Demand or in an LDAP server. The Directory Utility GUI allows you to add or update large numbers of users, groups, or sessions from an ASCII file, instead of individually through the Administration client.
There is a sample.xml which is already provided in the DirUtil folder. The text file needs to be in XML format, with an .xml extension for the GUI to recognize the options.
On Windows 64 bit OS, the utility can be launched with DirUtilGUI.bat which is located in the C:\Program Files\IBM\HostOnDemand\lib\samples\DirUtil directory.
On Windows 32 bit OS, the utility can be launched with DirUtilGUI.bat which is located in the C:\Program Files (x86)\IBM\HostOnDemand\lib\samples\DirUtil directory.
On a Unix/Linux based OS, the utility can be launched with DirUtilGUI.sh which is located in the /opt/IBM/HostOnDemand/lib/samples/DirUtil directory.
Note:These are the default directories where HOD is installed. In case HOD is installed in a user defined directory location would be the <<HOD_INSTALL_DIRECTORY>>\lib\samples\DirUtil directory. The command or script files are called:
The GUI has the User name and the Password fields where the user name and password of an administrtor are required. By default, admin is set as the user name and password is set as the password.
Host name is pre-defined as localhost and port number is pre-defined as 8999. You also can enter the desired hostname and port number in case of changes.
You need to chose the XML File that contains details about the user,the group, or the session. Your options include Add, Update, and Delete.
The checkbox Generate HTML file for List action is used to generate a list of users or groups as per the option defined in the xml file. The HTML file field is auto generated when the XML file is selected. The automatically generated html file would be named with the xml file name and placed in the same location of xml file.
Generating list of User(s) or Group(s) on the html file is valid only when the checkbox Generate HTML file for List action is checked and list of User(s) or Group(s) would be listed in the default HTML file if unchanged.
You can clear the console output by clicking the Clear button. You can also copy it to clipboard with the click of Copy button.
You can click Help to open the help content of DirUtilGUI.
Here are two examples of generating list action on the HTML file:
<action type = "list">
<userlist>
<userid>*</userid>
</userlist>
</action>
<action type = "list">
<grouplist>
<groupid>*</groupid>
</grouplist>
</action>
The descriptions of the elements below describe the format for valid XML elements that can be included in the XML file used by Directory Utility. A basic understanding of XML is assumed. Lines that begin with an "<!--" and end with "-->" are treated as comments. Elements are case sensitive.
To create or edit the XML file, you must use an ASCII editor that generates valid unicode characters. If you receive the error DIR0037 Fatal error: Invalid XML Character while using the XML file with the Directory Utility, the ASCII editor did not generate valid unicode characters. Use a different ASCII editor that does generate valid unicode characters.
<dirscript><action><group><groupid><description><parent><removeusers><user><userid><groupid><description><authentication><pw><nativeid><savepref><session><filename><groupid><userid><description><userlist><userid><groupid><filename><grouplist><userid><groupid><filename>
The root element in the XML file that contains all the other elements, and identifies the document as one that can be processed by the Directory Utility.
Attributes: none
Required elements: <action type=xxx>
Optional elements: none
The action that is performed on the elements enclosed in the <action> element. You can have multiple action elements within the <dirscript> element. Elements placed outside either the <dirscript> element or this element in the XML file are ignored by the Directory Utility.
Values: add, delete, update, or list
Required elements: At least one of the following is required within the <action> element:
 |
Directory Utility does not support the <grouplist> element for LDAP. |
The enclosing element for a group.
Attributes: none
Required elements:
groupid is converted to uppercase when the group is added. If you
are using LDAP the groupid can be mixed-case.Optional elements:
The enclosing element for a user.
Attributes: none
Required elements:
userid is converted to lower-case. If you are using LDAP the userid
can be mixed-case.Optional elements:
The authentication used for the user. You can use either native authentication, only if you are also using LDAP, or password authentication. No authentication will be configured for the user if this element is not specified when the action type is add, or if native is selected and you are not using LDAP.
Attributes: pw or native
Required elements:
Optional elements:
The enclosing element for a session.
Attributes: none
Required elements:
At least one of the following element types is required in the <session> element:
| You can specify multiple users or multiple groups in the session element, but
you cannot specify both users and groups in the same session element. |
Optional elements: none
The enclosing element for a user-based search.
Attributes: none
Required elements: Not more than one of each of the following elements can be used:
| If either the <userid> or the <groupid> tag is
missing, Directory Utility assumes a wildcard for the element and runs the search accordingly. |
Optional elements: Use this element only once, to refer to only one file:
| The Directory Utility writes
to a default file if you do not specify a file name. That default file is
DirUtilList.xml, which resides in the
hostondemand\lib\samples\DirUtil directory. Every time you do not
specify an output file, the list function adds the results of your search
to DirUtilList.xml. See Using output of the List
function. |
The enclosing element for a group-based search.
|
Directory Utility does not support this element for LDAP. |
Attributes: none
Required elements: Not more than one of each of the following elements can be used:
| If either the <userid> or the <groupid> tag is
missing, Directory Utility assumes a wildcard for the element and runs the search accordingly. |
Optional elements: Use this element only once, to refer to only one file:
| The Directory Utility writes
to a default file if you do not specify a file name. That default file is
DirUtilList.xml, which resides in the
hostondemand\lib\samples\DirUtil directory. Every time you do not
specify an output file, the list function adds the results of your search
to DirUtilList.xml. See Using output of the List
function. |
Below is an example XML file demonstrating the add and list actions. It adds three groups, adds the users to the groups, and if the sessions are exported and the comments are removed, then adds the sessions to the users and the groups. (To delete or update users, groups, or sessions, change the action type to delete or update and change the elements accordingly.) On Windows NT and Windows 2000 this sample file, called sample.xml, is located in the C:\Program Files\IBM\HostOnDemand\lib\samples\DirUtil directory. The sample.xml text file for the other operating systems is located in the hostondemand\lib\samples\DirUtilCommandFiles directory.
| This example uses the list
action in its simplest form: it sends a list of all users and groups to
the default XML output file of Directory Utility. To learn about more
sophisticated searches and how to use their output, see Searching with the List function. |
<?xml version="1.0" encoding="UTF-8"?>
<!-- Begin DTD - The DTD should not be modified.-->
<!DOCTYPE dirscript [
<!ELEMENT dirscript (action)+>
<!ELEMENT action (group | user | session)+>
<!ELEMENT group (groupid, description?, parent?, removeusers?)>
<!ELEMENT user (userid, groupid*, description?, authentication?, savepref?, removegroupid?)>
<!ELEMENT session (filename?, (groupid | userid)+, description?)>
<!ELEMENT groupid (#PCDATA)>
<!ELEMENT userid (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT userlist (userid+, groupid+, filename+)>
<!ELEMENT grouplist (userid+, groupid+, filename+)>
<!ELEMENT parent (#PCDATA)>
<!ELEMENT removeusers (#PCDATA)>
<!ELEMENT removegroupid (#PCDATA)>
<!ELEMENT authentication ((pw?, changepw?) | (nativeid))>
<!ELEMENT pw (#PCDATA)>
<!ELEMENT changepw (#PCDATA)>
<!ELEMENT nativeid (#PCDATA)>
<!ELEMENT savepref (#PCDATA)>
<!ELEMENT filename (#PCDATA)>
<!ATTLIST action type (add | delete | update | list) #REQUIRED>
<!ATTLIST authentication type (pw | native) #REQUIRED>
]>
<!-- End DTD -->
<dirscript>
<action type="add">
<!-- Add three groups -->
<group>
<groupid>3270GROUP</groupid>
<description>Group with 3270 sessions</description>
</group>
<group>
<groupid>5250GROUP</groupid>
<description>Group with 5250 sessions</description>
</group>
<group>
<groupid>mygroup</groupid>
<description>Group with parent</description>
<!-- the parent element should only be specified if using LDAP -->
<!-- <parent>3270GROUP</parent> -->
</group>
<!-- Add a user to the 3270 group and give them a password. -->
<user>
<userid>user1</userid>
<description>First User</description>
<authentication type="pw">
<pw>mypw</pw>
<changepw>yes</changepw>
</authentication>
<groupid>3270GROUP</groupid>
</user>
<!-- Add a user to the 5250 group and do not allow them to save their session preferences -->
<user>
<userid>user2</userid>
<description>Second User</description>
<authentication type="pw">
<pw>mypw</pw>
<changepw>yes</changepw>
</authentication>
<groupid>3270GROUP</groupid>
<savepref>no</savepref>
</user>
<!-- The session elements are commented because the file may not exist. -->
<!-- If you would like to add a session, then export a session with the -->
<!-- correct file name and remove the comment tags before running DirUtil. -->
<!-- Add a session to the 3270 group -->
<!--
<session>
<description>3270 Display</description>
<filename>3270dsp.hod</filename>
<groupid>3270GROUP</groupid>
</session>
-->
<!-- Add a session to the 5250 group -->
<!--
<session>
<description>5250 Display</description>
<filename>5250dsp.hod</filename>
<groupid>5250GROUP</groupid>
</session>
-->
<!-- Add a session to user1 -->
<!--
<session>
<description>3270 Printer</description>
<filename>3270prt.hod</filename>
<userid>user1</userid>
</session>
-->
</action>
<!-- List all users and all groups in the system and send output to the default XML output file -->
<!--
<action type = "list">
<userlist>
<userid>*</userid>
</userlist>
<grouplist>
<userid>*</userid>
<groupid>*</groupid>
</grouplist>
</action>
-->
</dirscript>
| Search basics | |
| Using wildcards | |
| Search examples |
Search basics
Invoke the list function by designating it as a value for an action
type: <action type="list">. Next you
specify either, or both, of two search types (which apply to existing
users and groups only):
|
Group-based searching is not supported for LDAP. |
For each search type, you can define criteria only with the <userid> and <groupid> elements. You do, however, have the flexibility to incorporate wildcards into your search criteria. Because you can use any number of wildcards, and place them at any location in the search string, you can make a search as open as you like.
Default criteria: When you do not specify one of the <userid> or <groupid> elements (or fail to specify both elements), the list function defaults to a wildcard assumption for the element(s). You are therefore assured of the most open search possible.
Directory Utility writes your search output to an XML file.
Using wildcards
The wildcard character is
the asterisk (*).
Directory Utility supports virtually any wildcard placement for the two searchable tags, <groupid> and <userid>. Wildcards may appear in either searchable element, both elements, or neither. They can appear any number of times, interspersed with alpha-numeric characters, or by themselves. If you omit either of the two ID tags from the search criteria, Directory Utility assumes the element to be a wildcard (*), and performs the wildcard search for that tag by default.
Examples of valid wildcard placement:
| <userid>*</userid> | All users |
| <groupid>*</groupid> | All groups |
| <userid>a*</userid> <groupid>*</groupid> |
Users with ID starting with an "a" and in any group |
| <userid>a*s</userid> <groupid>hod</groupid> |
Users with ID starting with an "a" and ending with an "s," in the group hod |
| <userid>alhines</userid> <groupid>hod</groupid> |
User "alhines" in the group hod |
Search examples
Examples combining all of the elements within the list function:
| General summary information for the list function, such as a count of searches performed, follows the same structure as other Directory Utility summary information. You can send the list summary data to the console, log file, or both. |
Because all output from the list function is written to an XML file, you can immediately reuse it as input for other Directory Utility functions. In the XML output file, you simply change the action command from list to add, delete, or modify.
If you name an output file (with the tag <filename>) when you input search criteria, Directory Utility writes the list results in the directory and file you designate. See search examples. If you do not supply an output file name, Directory Utility stores results in the default file, DirUtilList.xml, which resides in the hostondemand\lib\samples\DirUtil directory. Every time you do not specify a file for search output, the list function appends your results to DirUtilList.xml.
If you mistakenly specify a nonexistent file path, the results are the same: Directory Utility writes to the default file, adding to its contents with every new search.
| For Unix environments: Ensure that the pathnames for your XML output files are valid according to your particular Unix operating system. For example, if your operating system does not recognize all characters in your file pathname, its interpretation of the unknown characters may render the file name invalid. Then you may not be able to open the output file and retrieve your search results. |
<dirscript>
<action type="list">
<userlist>
<userid>*</userid>
<groupid>*</groupid>
</userlist>
<grouplist>
<userid>*</userid>
<groupid>*</groupid>
</grouplist>
<action>
<dirscript>
You generate the following output in the default XML file, DirUtilList.xml:
<!--Searching based on: Userlist -->
<!--with: userid= * -->
<!-- groupid= * -->
<dirscript>
<action type="list">
<user>
<userid>user1</userid>
<groupid>hod</groupid>
<description></description>
<authentication>pw</authentication>
</user>
<user>
<userid>user2</userid>
<groupid>group2</groupid>
<description></description>
<authentication>nativeid</authentication>
</user>
</action>
</dirscript>
<!--Searching based on: Grouplist -->
<!--with: userid= * -->
<!-- groupid= * -->
<dirscript>
<action type="list">
<group>
<groupid>hod1</groupid>
<description>Hod Users</description>
<parent></parent>
</group>
<group>
<groupid>group2</groupid>
<description>Other Users</description>
<parent></parent>
</group>
</action>
</dirscript>