tklkup - A script to do LDAP directory lookups, edits, and displaying directory schema information.
This script is used to lookup and edit information from a LDAP directory server. It is GUI based with several buttons for selecting directory servers, search bases, attributes and for enabling the Directory Schema Search window.
This script has been tested on Solaris, RedHat 6.0 Linux, Mandrake 6.5 and ActiveState Perl 628 but should work with any system that has PERL and the required modules installed in it.
There are 2 files associated with the tklkup program in this tar file; dot.tklkup, and tklkup.
About the files.
dot.tklkup - This is the initialization file that should be put into each users home directory as .tklkup.
This file will have to be setup properly before the user can expect the tklkup script to work properly. The odds of this initialization file being setup correctly for anyone is ZERO. However the script can be run with this file to get a feel for how the script will look.
It allows the user to customize how tklkup will look and work for them. If the .tklkup files does not exist in a users home directory the program has a set of built-in defaults that it will use.
To be used this file must have user read permission.
There are 5 commands that can be used with this file; hand, attribute, server, limit, and port.
hand -> values: left or right. Defines where the attribute label box will be place. limit -> value: default is 30. Limits the number of search base(s) detected. port -> value: default is 389. User should set this to match their needs. nismapname -> Solaris Native LDAP uses nismapname to define the automounter directory branches. Default is to not use Solaris Native LDAP. Uncomment this line in the dot.tklkup file to enable this option. attribute -> attribute upon which the data search will be based. One attribute per line. There is one additional attribute that is always listed without any action by the user; Filter. This attribute allows the user to enter the I<COMPLETE> filter that will used to search for data. server -> name of the directory server that you wish to conduct the data search. One server per line. Each line can have one of two formats server: server name or server: server name: base The I<server: server name> format will try to use the root_dse function to define the base. It the root_dse returns the namingContexts attribute, that information will be use to determine the search base(s). If the root_dse returns undefined or has no namingContexts attribute, a null string will be the search base. In this case the user will have to define a search base in the server command of the .tklkup file. The I<server: server name: base> format will cause each of the defined servers to have it's own special initial search base and use this initial search base to find all of the other search bases. This is an attempt to do auto search base detection. Using this method has one I<draw back>, when changing to a different directory server there is a possible I<delay> on displaying the new server name and search base. This is due to the fact that TK and it's MainLoop() process are not multi-tasking. The new search base has to be acquired and setup before MainLoop() takes control of the process. Depending on the number of search bases this time period can be quite a few seconds. When switching between servers with the same base, the search base will I<not> be updated. This too can have a I<draw back> if there are new search bases in the new server but it saves time. None of this is a problem if all of your servers have the same DIT layouts. Just define them with the same search base, there should be little or no delay when switching to the new server. Now a word about directory branch, or search base, detection. There are many things that can prevent this function from working properly. Several version 2 LDAP servers that this was tested on required that you be bound to the server. None of the version 3 LDAP servers required this. If this function does not work for you, provide a bind DN and password. The normal mode of operation for this function is an anonymous bind situation. Some of the ldap servers I worked with would never return the information I expected, auto detection never functioned on these systems. There is one college ldap server on the Internet that has so many bases that it takes over an hour to figure out all the search bases. The only way the operator knows that the script is still working is because search limit exceeded messages are displayed on the console that initiated the tklkup script. Who wants to wait a hour while the script figures this out. If you decide to use auto search base detection you will just have to try it and hope it works.
tklkup - PERL executable file.
You may need to change the first line of the PERL tklkup script to point to your file pathname of perl.
When executed tklkup will display a window on your computer. The graphical user interface, GUI, has several sections to it.
If tklkup is run on a HPUX, Sun, or Linux system the tklkup process will fork and run in background mode. If tklkup is run in debug mode or on a system that is not listed above it will NOT fork and will run in in foreground mode.
Exit button. At the top of the GUI is the "Exit" button. When a mouse click is done on the "Exit" button the program will terminate.
The SET LDAP VERSION "RadioButton" diamond will select the LDAP protocol version. When selected the "RadioButton" diamond will be red in color. This indicates that the ldap connection will use the version 3 protocol. To use ldap version 2 protocol press the "RadioButton" diamond so that it becomes a gray color.
The SELECT SERVER button will activate a drop down menu. From the menu the user will select the "RadioButton" that corresponds to the directory server the user wishes to use. When selected the "RadioButton" diamond will turn red in color. This menu is a designed to be a "tear off" menu, selecting the "---------------" line will cause the pull down menu to become a separate window that is still somewhat controlled by the GUI. The DIRECTORY SERVER text box will display the directory name that is selected. If the GUI is icon-ed or exited, the tear off window will follow the actions of the GUI. All other actions like moving or closing just the torn off window must be done by the user's window manager.
The BIND TO DIRECTORY button will activate a window that is separate from the main window.
The new window contains two buttons and two text boxes. For security reasons nothing is initially displayed in the text boxes. Pressing the accept button with this setup will cause the bind DN and password to be set to null strings.
At the top of the window is a Cancel button, pressing this button will cancel the operation of setting the bind DN and password.
The DN text box is where the user will enter the DN to bind with.
The PASSWORD text box is where the user will enter the password for the DN. Star "*" will be shown for the characters as they are typed into the text box.
At the bottom of the window is the Accept button, pressing this button will set the bind DN and the password.
The SELECT BASE button will activate a cascading drop down menu that contains the NamingContexts of the directory server. This menu is a designed to be a "tear off" menu, selecting the "---------------" line will cause the pull down menu to become a separate window that is still somewhat controlled by the GUI. If the GUI is icon-ed or exited, the tear off window will follow the actions of the GUI. All other actions like moving or closing just the torn off window must be done by the user's window manager.
From the window that contains the NamingContexts the user can select a namingContext to display the bases assiocated with that naminContext. In a non-torn off menu to select a namingContext simply pass the cursor over the nameingContext, a new window containing the bases assiocated with that namingContext will be displayed. On a menu window that has been torn off, select the namingContext by clicking on the namingContext, a new window containing the bases assiocated with that namingContext will be displayed. From the bases menu the user will select the "RadioButton" that corresponds to the search base the user wishes to use in the directory search. When selected the "RadioButton" diamond will turn red in color. The DIRECTORY SEARCH BASE text box will display the directory search base that is selected.
The SELECT ADDITIONAL ATTRIBUTES button will activate a drop down menu. From the menu the user will select the "RadioButton" that corresponds to the attribute the user wishes to use in the directory search. When selected the "RadioButton" diamond will turn red in color. This menu is a designed to be a "tear off" menu, selecting the "---------------" line will cause the pull down menu to become a separate window that is still somewhat controlled by the GUI. If the GUI is icon-ed or exited, the tear off window will follow the actions of the GUI. All other actions like moving or closing just the torn off window must be done by the user's window manager.
The CLEAR ATTRIBUTE DATA button will clear out the text that appears in the Attribute Data text box.
The SET FILTER CONDITION button will activate a drop down menu. From the menu the user will select the "RadioButton" that corresponds to the filter conditions the user wishes to use in the directory search. When selected the "RadioButton" diamond will turn red in color. This menu is a designed to be a "tear off" menu, selecting the "---------------" line will cause the pull down menu to become a separate window that is still somewhat controlled by the GUI. If the GUI is icon-ed or exited, the tear off window will follow the actions of the GUI. All other actions like moving or closing just the torn off window must be done by the user's window manager. The four filter conditions control how the search filter will be created. Just to the side of the SET FILTER CONDITION button is a text box that displays the filter condition that is selected.
The OBTAIN ROOT DSE ENTRY button will attempt to obtain the root dse entry for the selected directory server. If the root dse entry is obtained a separate window will be displayed that will display the information obtained from the root dse entry. If the root dse entry can not be obtained then an error message window will be displayed.
The ATTRIBUTE DATA text box is where the user will enter the data to be searched for. The program will automatically put the beginning and ending parenthesis around the data. If the Filter attribute is selected this is where the COMPLETE filter is entered, the program will not modify this string in any way.
The DIRECTORY PORT button will activate a window that is separate from the main window.
The new window contains two buttons and one text box. If the user needs to change the TCP connection port, this is where it is done.
At the top of the window is a Cancel button, pressing this button will cancel the operation of setting the port number.
The text box is where the user will enter the port number to connect. Display in the text box is the current port number.
At the bottom of the window is the Accept button, pressing this button will set the port number.
The EXPLORE DIRECTORY SCHEMA button will activate the Directory Schema Search Window. For information about this window see the Schema section of the manual.
SEARCH button. At the bottom of the GUI is the "Search" button. When a mouse click is done on the "Search" button the program will execute a ldap search.
-------------------------------------------------------------------
When the SEARCH DIRECTORY button is pressed the Search Results window will be displayed.
At the top of the GUI is the "Close Display Search Result Window" button. When a mouse click is done on the "Close Display Search Result Window" button the Display Search Result window will be withdrawn. The window is not destroyed, it just made invisible and disabled.
The Search Result window can be destroyed by enabling the proper window manager destroy function.
The hierarchial text box is where the results of the directory search will be displayed. If there were valid results returned from the search a list of DN entry(s) will be displayed in the hierarchial list box. Selecting a DN will cause a LDAP Action window to appear in which the user can select to view, rename, edit, or delete the corresponding DS's directory data.
The LDAP Action window has 4 buttons inside of it;
DISPLAY - Will display A Directory Search Display window to appear with the corresponding data in it.
RENAME - Will display a MODDN INFORMATION window in which the user will input the needed information for modifing an entry's DN.
DELETE - Will cause the selected DN to be deleted from the directory.
EDIT - Will cause a Entry Edit Display window with the corresponding entry data in it. It is from this window that the user can change directory data. This window is discribed in detail later in this document.
CANCEL - Will cancel the action request for the select DN.
DIRECTORY SEARCH DISPLAY is the window where data for the selected DN is displayed. Data is displayed in the read only Directory Data text box. Associated with the Directory Data text box is the "RadioButton" that determines how often the data in the directory text box is cleared. If the "CheckButton" is selected, colored red, the directory data text box will be cleared out before each directory query. If the "CheckButton" is not selected the directory data text box will NOT be cleared out until the Clear Data button in clicked or the CLEAR DIRECTORY DATA ON EACH QUERY "RadioButton" is selected.
The Directory Data text box is where the results of the directory search will be displayed. With the cursor in the Directory Data text box you have access to additional functions when you depress the mouse "action" button. When the "action" mouse button is depressed a small text box with 4 additional functions will be displayed inside the Directory Data text box. These 4 functions are;
File -> This function exits the window. You can not edit the Directory Data text box because it is created as a read only text box. Edit -> This function gives the user 3 additional functions; Copy -> I do not know what this function does. Select All -> Highlights/Selects all of the text in the Directory Data text box. Unselect All -> Unselects all of the text in the Directory Data text box. Select/Unselect are used in-conjunction with the Copy function. Search -> This function gives the user 4 additional functions. Find, Find Next, Find Previous -> These functions find text in the Directory Data text box. Replace -> This function allows you to replace the text that is selected. However this is just a fake replacement as you can not edit the Directory Data text box because it is created as a read only text box. View -> This function gives the user 3 additional functions. Goto Line -> When selected will prompt the user for a line number, the line number being the line number the user wishes to see. What Line -> When selected will tell the user what line number the cursor is on. Wrap -> When selected will prompt the user to choose how to do line wrapping in the Directory Data text box.
The CLEAR DATA button will clear out the text that appears in the Directory Data text box.
If the Tk::JPEG module is installed in the user's Perl system, when a jpegPhoto attribute is read a separate JPEG PHOTO DISPLAY window will be display. Inside this window will be the jpeg photo, a list box containing the DN of the entry, and a CLOSE WINDOW button.
If the Tk::JPEG module is NOT installed in the user's Perl system, nothing will be displayed for the jpegPhoto.
The RENAME button will activate a window that is separate from the main window.
The new window contains two buttons, two text boxes and one checkbutton. The text boxes are initailized with data that corresponds the DN that was selected in the Search Results window. It is in these text boxes that the user will enter the data needed for the modrdn operation to take place.
At the top of the window is a Cancel button, pressing this button will cancel the operation of modifing the DN.
The Newrdn text box is where the user will enter the new RDN for the selected entry.
The Newsuperior RDN text box is where the user will enter the new superior RDN, or branch DN, for the selected entry.
At the bottom of the window is the Accept button, pressing this button will set the new RDN and the superior RDN.
The DELETE OLD RDN DATA check box controls whether the old entry information is deleted or not deleted. When the check box is selected, colored red, the old entry information will be deleted. This is the default action for this button. Unselecting the check box will cause the entry data to not be deleted.
It is from this window that the user can modify an entry's data. There can only be one of these windows active at a time. Attributes that contain binary information can NOT be modified with this program.
At the top of the window is the CANCEL ENTRY EDIT button. Pressing this button will cancel all pending data changes for this entry. It will also cause the window to be destroyed.
At the bottom of the window is the CHANGE DATA button. Pressing this button will cause all of the pending data changes to take place.
Just above the CHANGE DATA button is the ADD ATTRIBUTE button. Pressing this button gives the user the option of entering a new attribute name and value so that this information can be put into the entry.
In the middle of the window is the ENTRY DATA box. In this box is the all of the entry's current attributes along with their data.
Each line in the box is broken up into two parts; the attribute button and the attribute data list box. There is one attribute and data pair per line. Multi-valued attributes have one line per attribute value.
The first line in the ENTRY DATA box will be the DN of the entry. This line can not be edited.
To edit an attribute, press the button that has the attributes name on it. This will cause a ATTRIBUTE MODIFICATION window to be displayed. This window is discribed in detail later in this documentation.
When the user has finished making changes, press the CHANGE DATA button. This will start the process of making the change(s) in the LDAP directory. If any errors occur a error window will appear. After the error window is dismissed the ENTRY EDIT DISPLAY window will still be active. The user can at this point do what ever it takes to correct the problem.
If no errors occur the ENTRY EDIT DISPLAY window and the SEARCH RESULTS windows will be destroyed. This is due to the fact that the data in both windows is no longer valid. The user must research the LDAP directory to get the new updated information.
It is from this window that the user can modify an attribute's data. There can only be one of these windows active at a time.
At the top of the window is the CANCEL ATTRIBUTE EDIT button. Pressing this button will cancel all pending data changes for this attribute. It will also cause the window to be destroyed.
At the bottom of the window is the ACCEPT DATA CHANGE button. Pressing this button will cause all of the current data changes to be put into the pending data change queue.
In the middle of the window is the attribute data text box. It is in this text box that the user will find the current data for the attribute the user selected. Depending on the operation the user wants to do the user can change the data or leave the data as is.
Below the attribute data text box are three buttons, ADD, DELETE, and REPLACE. To the right of the REPLACE button is a check button that controls operations on multi-valued attributes during REPLACE operations.
If the user wishs to add a new value to an attribute; the user should enter the new data in the attribute data text box and then press the ADD button.
If the user wishs to delete the value from an attribute; the user should not bother the data in the attribute data text box and should press the DELETE button.
The attribute replace operation is a little tricky depending whether the attribute is single or multi valued.
If the user knows that the attribute is multi-valued and wants to preserve the other attribute values the user should press the check button to the right of the REPLACE button. Doing this will control how the add and delete operations are staged. The user should then enter the new data in the attribute data text box and press the REPLACE button.
If the user wishs to replace all of the values for an attribute; the user should enter the new data in the attribute data text box and press the REPLACE button.
When the user done with the changes the user should press the ACCEPT DATA CHANGES button. This will move the data changes onto the pending data change queue and close the window.
When the DELETE button is selected, before the actual deletion takes place, a window will be displayed with a Cancel and Accept buttons. This gives the user a fail safe in case the user selects the DELETE button by accident. Pressing the Cancel will cancel the delete request, pressing the Accept button will cause the directory entry to be deleted.
This function is used to lookup schema information from a LDAP directory server. The directory server to be searched is selected from the Directory Search window.
When the Explore Directory Schema button is pressed in the Directory Search window, the Directory Schema Search window will be displayed on your computer. The graphical user interface, GUI, has several sections to it.
At the top of the GUI is the "Close Schema Search Window" button. When a mouse click is done on the "Close Schema Search Window" button the schema window will be destroyed.
The Directory Schema Search window can be destroyed by enabling the proper window manager destroy function.
When the Write Data To File RadioButton is selected the LDAP Schema data will be written to the file listed in the text box below the RadioButton text. Once the data has been written to the file a message will be written to the DIRECTORY SCHEMA DATA text box stating that the data has been written to a file and will list the file name. Upon completion of the schema dump operation the RadioButton and text in the file name text box will be reset.
Associated with the Directory Schema Data text box is the "CheckButton" that determines how often the data in the directory text box is cleared. If the "CheckButton" is selected, colored red, the directory data text box will be cleared out before each directory query. If the "CheckButton" is not selected the directory data text box will NOT be cleared out until the Clear Data button in clicked or the CLEAR DIRECTORY DATA ON EACH QUERY "CheckButton" is selected. By default the CheckButton is select to clear out the data in the Directory Schema Data text box on each query.
Associated with the Directory Schema Data text box is a series of "CheckButtons" that determines what of the schema objects will be displayed. There are 9 Checkbuttons; ALL, objectClass, matchingRules, attributeTypes, ldapsyntaxes, nameforms, ditstructurerules, ditcontentrules, and matchingruleuse. If the "CheckButton" is selected, colored red, then schema objects of that type will be displayed in the Directory Schema Data text box. If the "CheckButton" is not selected, gray in color, then schema objects of this type will not be displayed in the Directory Schema Data text box. By default the ALL CheckButton is select.
The Directory Schema Data text box is where the results of the directory search will be displayed. With the cursor in the Directory Data text box you have access to additional functions when you depress the mouse "action" button. When the "action" mouse button is depressed a small text box with 4 additional functions will be displayed inside the Directory Data text box. These 4 functions are;
The Clear Data button will clear out the text that appears in the Directory Schema Data text box.
The SHOW HIERARCHICAL OBJECTCLASS TREE will cause one of two windows to be displayed. For information about these windows see the HIERARCHICAL OBJECTCLASS section of the manual.
At the bottom of the GUI is the "Retrieve Directory Schema" button. When a mouse click is done on the "Retrieve Directory Schema" button the script will query the directory server for schema information.
If no directory schema data has been obtained from the selected directory server a error message window will be displayed stating that no schema data is available.
If directory schema data has been obtained from the selected directory server a separate window will be displayed. The HIERARCHICAL OBJECTCLASS window has two list boxes and a CLOSE HIERARCHICAL DISPLAY WINDOW button. The CLOSE HIERARCHICAL DISPLAY WINDOW button will destroy the HIERARCHICAL OBJECTCLASS window. In one of the list boxes will be a hierarchial tree of all of the objectclasses obtained from the directory server. Doing a mouse button select on one of the objects in the tree will cause information about that objectclass branch to be displayed in the adjacent list box. The most superior ojectclass will be at the top of the listing, the leaf objectclass will be at the bottom of the listing. Each objectclass is separated by a dashed line. All information about each objectclass will be displayed in that objectclass's section.
To use this program you will need the following.
At least PERL version 5.004. You can get a stable version of PERL from the following URL; http://cpan.org/src/index.html
Perl Tk800.022 module. You can get this from the following URL; ftp://ftp.duke.edu/pub/CPAN/modules/by-module/Tk/
If you wish to display a jpegPhoto attribute then you will need the Perl Tk-JPEG-2.014 module. You can get this from the following URL; ftp://ftp.duke.edu/pub/CPAN/modules/by-module/Tk/
Perl LDAP module. You can get this from the following URL; ftp://ftp.duke.edu/pub/CPAN/modules/by-module/Net/
Perl Convert-ASN1 module. You can get this from the following URL; ftp://ftp.duke.edu/pub/CPAN/modules/by-module/Convert/
Depending on the modules loaded in your PERL system, you may need to load the following PERL module.
Perl Digest-MD5 module. You can get this from the following URL; ftp://ftp.duke.edu/pub/CPAN/modules/by-module/MD5/
Bundled inside each PERL module is instructions on how to install the module into your PERL system.
Install the tklkup script anywhere you wish, I suggest /usr/local/bin/tklkup.
Install the dot.tklkup file in each users home directory as .tklkup. It is possible to use a central copy and create a link in the user home directory to the central copy.
Since the script is in PERL, feel free to modify it if it does not meet your needs. This is one of the main reasons I did it in PERL. If you make an addition to the code that you feel other individuals could use let me know about it. I may incorporate your code into my code.
Clif Harden <charden@pobox.com> If you find any errors in the code please let me know at charden@pobox.com.
Copyright (c) 1999-2001 Clif Harden. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
1 POD Error
The following errors were encountered while parsing the POD:
=back doesn't take any parameters, but you said =back 4 -------------------------------------------------------------------
To install Net::LDAP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::LDAP
CPAN shell
perl -MCPAN -e shell install Net::LDAP
For more information on module installation, please visit the detailed CPAN module installation guide.