Information Center

Using the Directory Utility

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

Running the Directory Utility

The Directory Utility can be run using either a graphical user interface or a command line interface.

Graphical user interface

To start the graphical user interface ...

In the Directory Utility graphical user interface enter the following fields as appropriate:

Connection Properties
User ID
The Host On-Demand administrator's user ID.
Password
The Host On-Demand administrator's password.
Host
The Host On-Demand service manager's hostname or IP address. This field is optional. The default is localhost (127.0.0.1).
Port
The Host On-Demand service manager's port. This field is optional. The default is 8999.
File Operations
Input XML File
The name of the XML file that contains the actions you want to perform. See XML file format / element descriptions.
Browse
Click to browse for the input XML file.
Generate HTML file for list action
Select this option when the action in the input XML file is list, and you want the list results displayed in an output HTML file.

This option is ignored for the add, delete, and update actions in the input XML file.

Output HTML
The name of the output HTML file to display the list results.
Browse
Click to browse for an existing output HTML file.
OK
Click to run the Directory Utility using the specified input XML file.
Cancel
Click to cancel.
Help
Click for Help.
Output
Console
This is the output area that displays a summary of the results of the actions in the input XML file.
Clear
Click to clear the Console area.

Command line interface

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

where the following are used:

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


Using the Directory Utility GUI

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.

Running the Directory Utility GUI

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:

Interface of the GUI

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.

Using output of the List function

Here are two examples of generating list action on the HTML file:

XML file format / element descriptions

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>


<dirscript>..</dirscript>

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


<action type=xxx>..</action>

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:

<group>..</group>
The group that is affected by the action. If the action is add and the group already exists, you will receive a message that the group is a duplicate.


<user>..</user>
The user that is affected by the action. If the action is add and the user already exists, you will receive a message that the user is a duplicate.


<session>..</session>
The session that is affected by the action. The session element is not valid when the action is update. If the session already exists, a new session named "1:description" is added, the same way that the Administration client adds a duplicate session.


<userlist>..</userlist>
Valid only if the action is list. Creates an output XML file of user-specific information. See Searching with the List function.


<grouplist>..</grouplist>
Valid only if the action is list. Creates an output XML file of group-specific information. See Searching with the List function.
Directory Utility does not support the <grouplist> element for LDAP.

<group>..</group>

The enclosing element for a group.

Attributes: none

Required elements:

<groupid>..</groupid>
A unicode text string that identifies the group in LDAP or Host On-Demand. If you are using Host On-Demand the groupid is converted to uppercase when the group is added. If you are using LDAP the groupid can be mixed-case.

Optional elements:

<description>..</description>
A unicode text string that describes the group. This element is only valid when the action type is add or update.
<parent>..</parent>
The parent of this group. This element is only valid when the action is add or update, and when using LDAP. If this element is not specified when the action is add, the group is added to the top level.
<removeusers>..</removeusers>
This element allows you to delete all the users which belong only to this group when you delete the group. This element is only valid when the action is delete, and this element is not valid when using LDAP. Valid values are Yes and No. If Yes is specified then the users in this group will be deleted when the group is deleted. If No is specified and there are users in the group, the users which belong only to this group are moved to the HOD group and the group is deleted.

The Default is No.

If you have many users, it may take some time for the processing of this element to complete.

<user>..</user>

The enclosing element for a user.

Attributes: none

Required elements:

<userid>..</userid>
The user identifier. This element is always required. If you are using Host On-Demand the userid is converted to lower-case. If you are using LDAP the userid can be mixed-case.
<groupid>..</groupid>
The group to which the user is being added. This element is required when the action type is "add" and ignored when the action type is delete. If you are not using LDAP you can specify multiple <groupid> elements. If you are using LDAP and you specify multiple groups, an error message is generated and the user is not added. Groups specified must exist before you can add a user to them. If the action type is update, the user is updated to have membership in this group.

Optional elements:

<description>..</description>
A unicode text string that describes the user.
<authentication type=xxx>..</authentication>
You can specify the authentication that is used for the user. Valid types are native and pw. If this element is not specified, then no authentication will be configured for the user.
<savepref>..</savepref>
You can specify if the user is authorized to save preferences (changes that the user might make to a host session configuration). Valid values are Yes or No. If this element is not specified the default of Yes is set for the user, so that the user is able to save preferences.
<removegroupid>..</removegroupid>
You can update a user so that they no longer have membership in the specified group. This element is only valid if the action type is update. You must use a valid groupid which contains this user.

<authentication type=xxx>..</authentication>

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:

<nativeid>..</nativeid>
The user ID of the user on the native operating system. This element is required and valid only when using LDAP and when the authentication type is native.

Optional elements:

<pw>..</pw>
The password associated with the user. This element is only valid when the authentication type is pw.
<changepw>..</changepw>
You can specify if the user is authorized to change their password. Valid values are Yes or No. If this element is not specified the default of Yes is set for the user, and the user is able to change their password. This element is only valid if the authentication type is pw and is ignored if the authentication type is native.

<session>..</session>

The enclosing element for a session.

Attributes: none

Required elements:

<filename>..</filename>
The file containing the session definition. You can create a session definition file by using the Export Session menu option from any defined Host On-Demand session. The default extension for session files is .hod. The <filename> element may contain the full path to the session file, and it is only required when adding a session.
<description>..</description>
A unicode text string that describes the session and is used as the session name. The <description> is required to update or delete a session. If <description> is omitted the session name will be used for the description of the file.

At least one of the following element types is required in the <session> element:

<userid>..</userid>
The user identifier for the user to which this session is being added. User IDs must already exist before the session can be added. You can include multiple <userid> elements to add this session for multiple users.
<groupid>..</groupid>
The group identifier for the group to which the session is being added. Groups must already exist before the session can be added. You can include multiple <groupid> elements to add a session for multiple groups.
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


<userlist>..</userlist>

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:

<userid>..</userid>
The user ID to be used in the search criteria.

<groupid>..</groupid>
The group ID to be used in the search criteria.

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:

<filename>..</filename>
The file to which Directory Utility writes XML output. You must name this file with a valid XML file name.
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.

<grouplist>..</grouplist>

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:

<userid>..</userid>
The user ID to be used in the search criteria.

<groupid>..</groupid>
The group ID to be used in the search criteria.

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:

<filename>..</filename>
The file to which Directory Utility writes XML output. You must name this file with a valid XML file name.
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.

XML file example

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>

Searching with the List function

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):

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:

<userlist>
<userid>*</userid>
<groupid>*</groupid>
<filename>my.xml</filename>
</userlist>
Perform a user-based search (meaning return user-based output)
for all users in all groups, and send output to my.xml.
<grouplist>
<userid>a*</userid>
<groupid>hod</groupid>
<filename>your.xml</filename>
</grouplist>
Perform a group-based search (meaning return group-based output)
for the group hod that contains a user ID starting with an "a," and send
output to your.xml.

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.


Using output of the List function

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.

Output sample
If you input the following:
<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:
(So that you can keep track of your searches, Directory Utility displays your original criteria as comments at the beginning of the file.)
<!--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>