Pegasus Mail LDAP Extension

LDAP (Lightweight Directory Access Protocol) is an implementation of the X.500 directory services standard for Internet clients using the TCP/IP protocol. It allows you to look up information for people using a minimum of information about that person. The extension can search for people using their surname, given name, division (OU in X.500 terms), phone number or e-mail address and you can tell it to search in a number of ways. You can use the results of your searches to start new mail messages, or as a quick way of creating address book entries for future use.

In order to use this extension, you must know the name or address of a machine that is running the LDAP server software that holds the information for the organization in which the person you wish to find resides.

Setting up directories

Making a query

Using the results of a query

Some sample public LDAP servers

Troubleshooting


Setting up Directories

Before you can make a query, you need to tell the LDAP extension a little information that it uses to establish the connection to the LDAP server and when forming the request for information. To do this, you create a directory, or an entry that contains all the information the program needs. The program remembers directories from session to session, so once you have created a directory, you can use it over and over again for as long as you wish. You can create as many directories as you wish, and your system manager can also create public directories that are shared by all people on the system.

To create a directory, click the Setup button in the LDAP extension's main window.

A window will open showing a list of the directories that are currently defined on your system. To create a new directory, click the button labelled New and another window will open: this is the directory editor window, and it is here that you provide the information the program needs to make the LDAP query for you.

Creating and editing directory entries

You can edit a directory entry by double-clicking on it in the list, or by highlighting it in the list and pressing the Edit button. This is also how you rename an entry - simply change the title for the entry in the editing screen without changing any of the other information.

To delete directory entries that you no longer need, highlight them in the list and click the Delete button.

Rearranging the list

The two arrow buttons, [image] and [image] can be used to rearrange the order of the items in the directory list. To move an item to the top of the list, highlight it then click the "Up" button until it is at the top. You will usually put the directories you use often near the top of the list so that they are easy to access in the directory control. The order of the entries is remembered from session to session.


Creating and editing directory entries

A directory entry contains the information Pegasus Mail needs to connect to the server and process your query.

Title for this directory entry  You can type in a descriptive name for the directory here. The program will show this in the Using this directory control on its main window. You can enter anything you wish here, up to fifty characters in length. The title is intended for your benefit, so you should enter something that will help you to identify the directory easily.

Host name  Enter here the name or address of the computer that is running the LDAP server you want to query. Your system manager will usually be able to tell you the proper contents for this field. Note that a host name is required here, not an e-mail address: if what you have entered contains an '@' symbol, it is almost certainly incorrect.

Port  A port is like an electrical socket on the wall - the program plugs into it in order to make a connection to the LDAP server. If you plug your blender into a television aerial socket, it probably won't work very well - well, it's just the same on the Internet with servers and ports. Each server has its own port, and you have to plug in to the proper port to get the service. The usual port for an LDAP server is 389, but in some specialised cases the server may use a different port. Your system manager can tell you if you need to change this value.

Search root  Imagine for a moment that you wanted to find someone called Smith, who worked for the U.S. Bureau of Martians. Now, you could go to the LDAP server for the U.S. Federal Government and ask it to tell you all the users called Smith, but as you can imagine, the result might be a great many names. Since you know that the person works for the U.S. Bureau of Martians, you can use this information to narrow the search, by providing what is known as a Distinguished Name for an Organizational Unit in this field. An organizational unit is the name of some functional subset of an organization - in this case, the U.S. Bureau of Martians, as a division of the U.S. Government. A distinguished name is a special standard way of writing the name of that organizational unit that allows it to be found on a network. Distinguished names, (or DNs) must be written using a special syntax identifying the name of the organizational unit, the name of the organization, and the country in which it is found. An example of a DN might be the following for the Development division of Pegasus Mail in New Zealand:

OU=Development, O=Pegasus Mail, C=NZ

The OU=, O= and C= are  special characters that indicate what each part of the DN is: "OU", for instance, stands for "Organizational Unit". The LDAP server uses this DN to start searching at a specific point in the directory hierarchy for the organization. So, taking our example from above (and we stress that this is a fictional example, if you hadn't already worked that out), you might be able to enter the following search root for your query:

OU=Bureau of Martians, O=US Government, C=US

Not every LDAP server will require a search root, but some LDAP servers absolutely require one. You cannot manufacture a root path - you need to know it. Regrettably, there's no easy way of finding a root path. If you need to look up addresses at an organization with which you are unfamiliar, you may have to send an e-mail message to the postmaster at that site to find out what search root is required when searching their LDAP server.

We realise that this all sounds like gobbledigook, and we agree with you, but it's very hard to explain it any other way, and unfortunately, it's an important part of the protocol. We would like to make it simpler for you, but we can't. We do sympathise, though.

Type of connection  Most of the time, you will make anonymous queries - that is, you will not need to tell the LDAP server who you are: you can simply connect to it and say "Tell me about the Smiths you have". Sometimes, however, you may find that an LDAP server will give you the minimum of information if you make an anonymous connection, and you may encounter some LDAP servers set up by paranoid system administrators, where no information at all is made available to anonymous queries. In cases like this, it may be possible to get more information by telling the LDAP server who you are. You do this by giving a username (which need not be your actual user name on any computer system), and then a password to show that you are authorised to use that user name. Clearly you have to know the username and password: your system administrator will be able to give you the username and password you should use if it is ever necessary.

When you have filled in the necessary fields, click the OK button to save the entry.


Making a query using the LDAP Extension
Making a query with the LDAP Extension

The first step in making an LDAP query is to fill in the three controls near the top of the LDAP extension's main window:

Select the information you want to use as the basis of your search in the first of the three controls. If you know a person's surname, then you will choose Surname; if you want to find the people who work in a particular unit of the company, you will choose Division and so on.

The second of the three controls determines how the search should be made. If you set it to Contains, then any entry containing the text you type will be returned to you. So, for example, if you ask for Surnames containing "John", you might get "Johnson", "Applejohn", or "Veljohnson" back from the search. If you set the control to Is, then only entries that are the same as what you have typed will be returned. If you set the control to Is like, then the server will try to match words that are phonetically similar to what you have entered - for example, if you ask for surnames that are like "Stephens", you may well get "Stevens" returned from the search.

Important note:  Not all servers implement the Is like capability, and some do it better than others. Your mileage may vary with this feature.

The final control simply contains what you want to search for - type in whatever you need. The program remembers the last twenty searches you have made - you can select them from the list by clicking on the down-arrow at the right of the control, or by scrolling using the up and down arrow keys on the keyboard. Note that searches are almost always case-insensitive, so "SMITH is the same as "Smith".

Advanced Queries

The LDAP Extension will also accept any valid query using the syntax defined in RFC1558. If the first character in the "Name" field is a bracket - '(' - then the Extension will present your query to the LDAP server unmodified. For more information on this kind of search, please consult RFC1558, which is available via FTP from nic.ddn.mil and other sites.

When you have constructed your query, click the Query button and the extension will present your request to the LDAP server specified in the directory you have chosen. Any results of the query will be presented to you as a list in the Results window.


Using the results of a query
Using the results of an LDAP query

When you have made a successful query, the results will appear in the Results window. Clicking on any entry there will present full details about that entry in the Details window. The three columns in the Results window can be resized by clicking and dragging on the spaces that divide them (the cursor will change when this is available). You can also sort on any of the three columns by clicking the heading above that column. The column that is currently being used to sort the list will display its heading control in bold.

You can use the results in a number of ways.

Double-clicking on any entry in the result list will start a new e-mail message to that person.

Copying text:  the Details window is a standard Windows Edit Control, and you can copy its contents at any time by highlighting it and pressing <Ctrl+C> to copy it to the clipboard. You can subsequently paste the text as you would normally do.

Dragging addresses to messages:  you can drag an entry from the Results list to any open message in Pegasus Mail and drop it on an address field (To:, or Cc: for instance). The e-mail address from the entry will be pasted into the field where you drop the data. You can also drag more than one result at a time if you wish - select more than one entry in the result list using Ctrl+Click or Shift+Click.

Dragging entries to address books:  you can drag an entry or entries from the results list to any open or minimized address book on the WinPMail desktop. WinPMail will create a new entry in the address book containing the information from the search.

Dragging results to the message body:  You can drag an entry or entries from the results list to the message body of any open message and Pegasus Mail will insert the data from the results into that message for you. This is a handy way of sending a person's address details to someone else who does not have access to LDAP services.


Some sample public LDAP servers

Several services offer LDAP lookup facilities - here are some you can try. Please note that to the best of our knowledge these are public servers, but if you use them extensively, you should enquire from the service provider to make sure of this.

Four11:	Host: 	ldap.four11.com

Search root:	"c=xx" (replace with country code)

Infospace:	Host: 	ldap.infospace.com

Search root: 	"c=XX" (replace with country code)

BigFoot:	Host:	ldap.bigfoot.com

Search root: 	"c=XX" (replace with country code)


Troubleshooting

Occasionally things go wrong. The following are common problems encountered using the LDAP extension:

The LDAP extension doesn't appear in my Extensions list

This usually means one of two things:

1: The extension has not been properly installed. You need to copy the contents of the distribution archive into the same directory as your copy of WINPMAIL.EXE or WINPM32.EXE. On some systems you may also have to copy the file NSLDAP.DLL into your Windows SYSTEM or SYSTEM32 directory.

2: Your system does not have a properly-configured WINSOCK.DLL. The LDAP extension uses the TCP/IP network protocol to make its queries and cannot run if that protocol (which is provided by WINSOCK.DLL) is not installed properly on your system. You may also have told Pegasus Mail not to use WINSOCK.DLL: make sure that you have chosen "On demand" or "Always" in your Advanced Settings preferences.

When I make a query, I see "An error occurred during the search"

This indicates that something has gone wrong during the search - there are a number of possibilities:

1: Your query may have been too broad. Many servers will only return a limited number of results, and if your query produces a number of matches in excess of the limit, you may get an error. Try modifying your query so that it is more precise.

2: You may have had a communication problem, especially if you are operating over a slow link. Try your query again.

3: In rare cases, the string you searched for may result in an improperly formed request. You should avoid using special characters, such as ", <, *, &, $ or international characters in your query wherever possible.

4: The server may not support the operation you are attempting - this is especially the case when you are using the "Is like" operator. Try using the "Is" or "Contains" operator instead.