LDAP Programming Management and Integration 1st

Edition Clayton Donley download

https://ebookname.com/product/ldap-programming-management-and-
integration-1st-edition-clayton-donley/

Get Instant Ebook Downloads – Browse at https://ebookname.com

Instant digital products (PDF, ePub, MOBI) available
Download now and explore formats that suit you...

Microsoft Direct3D Programming Kick Start 1st Edition

Clayton Walnum

https://ebookname.com/product/microsoft-direct3d-programming-
kick-start-1st-edition-clayton-walnum/

Ultrasonic Periodontal Debridement Theory and Technique

1st Edition Donley

https://ebookname.com/product/ultrasonic-periodontal-debridement-
theory-and-technique-1st-edition-donley/

Maximizing Healthcare Delivery and Management through

Technology Integration 1st Edition Tiko Iyamu

https://ebookname.com/product/maximizing-healthcare-delivery-and-
management-through-technology-integration-1st-edition-tiko-iyamu/

The Instruction of Imagination Language as a Social

Communication Technology 1st Edition Daniel Dor

https://ebookname.com/product/the-instruction-of-imagination-
language-as-a-social-communication-technology-1st-edition-daniel-
dor/
The Liars Club A Memoir 20th Anniversary Edition
Edition Mary Karr

https://ebookname.com/product/the-liars-club-a-memoir-20th-
anniversary-edition-edition-mary-karr/

Doing Oral History 3rd Edition Donald A. Ritchie

https://ebookname.com/product/doing-oral-history-3rd-edition-
donald-a-ritchie/

Evidence Based Pediatric Oncology 3rd Edition Ross

Pinkerton

https://ebookname.com/product/evidence-based-pediatric-
oncology-3rd-edition-ross-pinkerton/

Voyages From Tongan Villages to American Suburbs Second

Edition Cathy A. Small

https://ebookname.com/product/voyages-from-tongan-villages-to-
american-suburbs-second-edition-cathy-a-small/

European Nutrition And Health Report 2004 1st Edition

Ibrahim Elmadfa

https://ebookname.com/product/european-nutrition-and-health-
report-2004-1st-edition-ibrahim-elmadfa/
Seeking Order in a Tumultuous Age The Writings of Ch■ng
Toj■n a Korean Neo Confucian David M. Robinson

https://ebookname.com/product/seeking-order-in-a-tumultuous-age-
the-writings-of-chong-tojon-a-korean-neo-confucian-david-m-
robinson/
LDAP Programming, Management
and Integration
LDAP Programming,
Management and
Integration

CLAYTON DONLEY

MANNING
Greenwich
(74° w. long.)
For online information and ordering of this and other Manning books,
go to www.manning.com. The publisher offers discounts on this book
when ordered in quantity. For more information, please contact:
Special Sales Department
Manning Publications Co.
209 Bruce Park Avenue Fax: (203) 661-9018
Greenwich, CT 06830 email: [email protected]

©2003 by Manning Publications Co. All rights reserved.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted,

in any form or by means electronic, mechanical, photocopying, or otherwise, without prior
written permission of the publisher.

Many of the designations used by manufacturers and sellers to distinguish their products are
claimed as trademarks. Where those designations appear in the book, and Manning
Publications was aware of a trademark claim, the designations have been printed in initial
caps or all caps.

Recognizing the importance of preserving what has been written, it is Manning’s policy to have the
books we publish printed on acid-free paper, and we exert our best efforts to that end.

Manning Publications Co. Copyeditor: Tiffany Taylor

209 Bruce Park Avenue Typesetter: Dottie Marsico
Greenwich, CT 06830 Cover designer: Leslie Haimes

ISBN 1-930110-40-5
Printed in the United States of America
1 2 3 4 5 6 7 8 9 10 – VHG – 06 05 04 03
contents
preface xi
acknowledgments xv
about this book xvi
getting started xix
about the cover illustration xxii

Part 1 Fundamental LDAP concepts 1

1 Introduction to LDAP 3
1.1 What LDAP is 4
Directory services and directory servers 4 ✦ LDAP and directory
services 4 ✦ Other directory services 5
1.2 What LDAP is not 7
LDAP is not a relational database 7 ✦ LDAP is not a file system for
very large objects 7 ✦ LDAP is not optimal for very dynamic objects 9
LDAP is not useful without applications 9
1.3 Current applications 10
White pages 10 ✦ Authentication and authorization 12
Personalization 13 ✦ Roaming profiles 14 ✦ Public Key
Infrastructure 14 ✦ Message delivery 15
1.4 Brief history 15
X.500 and DAP 15 ✦ A new standard is born 16
LDAP goes solo 17 ✦ LDAPv3 18
1.5 LDAP revisions and other standards 18
Replication and access control 19 ✦ Directory Enabled
Networking 21 ✦ XML and directories 22
1.6 Directory management 23
1.7 Directory integration 24
Integration via metadirectories 27

v
 1.8 Integration and federation via virtual directory technology 30
1.9 Why this book? 31
1.10 Summary 32

2 Understanding the LDAP information model 34

2.1 Information model overview 35
Entries 35 ✦ Attributes 36 ✦ LDAP entries vs. database records 36
2.2 Working with LDAP schema 37
Standard LDAP schema 37
2.3 Attribute types 39
Defining attribute types 39 ✦ Syntax definitions 40 ✦ Matching rules for
attributes 41 ✦ Support for multiple values 43 ✦ Inheritance 44
User modification 45 ✦ Variables in Java, Perl, and C 45
2.4 Object classes 46
Defining object classes 46 ✦ Required and allowed attributes 47
Object class inheritance 47 ✦ Multiple object class memberships 48
Object class types 48 ✦ LDAP object classes and Java or C++ classes 50
2.5 Using object modeling to design LDAP schema 51
Modeling classes 51 ✦ Modeling relationships 51
Modeling object instances 53
2.6 Summary 54

3 Exploring the LDAP namespace 55

3.1 What is a namespace? 56
Hierarchical namespaces 57
3.2 Specifying distinguished names 59
Choosing a relative distinguished name attribute 60
Determining the base 62
3.3 Assigning the root naming context 64
Traditional style of assigning the root name context 64
Domain component style of assigning the root name context 65
3.4 Selecting and designing a directory tree 65
Intranet directories 66 ✦ Internet directories 69 ✦ Extranet directories 71
3.5 Summary 74

4 Search criteria 75
4.1 Performing a search 76
4.2 Where to search: base and scope 76
Search base 76 ✦ Search scope 77

vi CONTENTS
 4.3 What to evaluate: search filters 78
Presence filters 79 ✦ Exact equality filters 80 ✦ Substring matching 81
Ordered matching (greater than/less than) 83 ✦ Approximate filters 84
Multiple filters: AND and OR operators 84 ✦ Negative filters: the NOT
operator 86 ✦ Extensible searching and matching rules 86
4.4 What to return: the attribute return list 87
4.5 LDAP search criteria vs. SQL queries 87
Similarities between SQL SELECT and LDAP search criteria 88
Differences between SQL SELECT and LDAP search criteria 88
4.6 Increasing search performance 88
4.7 Summary 89

5 Exchanging directory information 90

5.1 Representing directory information outside the directory 91
5.2 LDAP Data Interchange Format 92
Expressing entries in basic LDIF 92 ✦ Writing LDAP changes
as LDIF 94 ✦ Representing schemas in LDIF 95 ✦ Advantages
and disadvantages of LDIF 96
5.3 Directory Services Markup Language 96
Why use DSML? 96 ✦ Getting started with DSML 98
A DSML example 98 ✦ Handling binary values in DSML entries 99
Entry changes and DSML 100
5.4 Defining directory schemas with DSML 100
DSML object classes 100 ✦ DSML attribute types 101
5.5 XSLT and DSML 102
Converting DSML to HTML using XSLT 102
5.6 Summary 104

Part 2 LDAP management 105

6 Accessing LDAP directories with Perl 107
6.1 LDAP access from Perl 108
6.2 Getting started with Net::LDAP 109
Using the module 109 ✦ Opening a connection 109
Binding to the directory 110
6.3 Searching with Net::LDAP 111
Performing a search 111 ✦ Understanding search scopes 113
LDAP search filters 115 ✦ Using search results 115 ✦ Limiting
attribute retrieval 115 ✦ Handling referrals 116

CONTENTS vii
 6.4 Manipulating entries 116
Updating an entry 116 ✦ Adding new entries 117
Deleting an entry 117 ✦ Renaming an entry 117
6.5 Comparing entries 118
6.6 Handling errors 119
6.7 Support for encrypted/SSL connections 119
6.8 Summary 120

7 Managing directory entries, groups, and accounts 121

7.1 Common types of managed entries 122
7.2 Entry management models 122
Centralized administration 122 ✦ Distributed administration 124
User self-administration/self-service 125
7.3 Creating people entries 126
People entries via a web form 127 ✦ People entries based on
existing data 130 ✦ Summary of creating entries 134
7.4 Creating and maintaining groups 134
Explicit groups 135 ✦ Dynamic groups and LDAP URLs 136
7.5 Representing and managing account information 136
Unix user accounts 137 ✦ Linking Unix accounts to people 141
7.6 Managing other information 142
Security services information 142 ✦ DNS information 142 ✦ Directory
Enabled Networking information 143 ✦ Card catalog information 143
7.7 Summary 143

8 Synchronizing LDAP information 144

8.1 Approaches to data flow management 145
Replication 145 ✦ File export/import 146 ✦ Scripting 146
8.2 Data flow analysis 146
Schema mapping 147 ✦ Determining the authoritative source 147
Data transformation 148 ✦ Namespace translation 149
8.3 Interchange formats 150
LDAP Data Interchange Format 150
Directory Services Markup Language 151
8.4 Migration to LDAP 152
Migrating a simple table 152 ✦ Migrating from multiple sources 154
Adding new information to existing entries 157
8.5 Joining related information 159
Multikey matches 159 ✦ Fuzzy matching 160

viii CONTENTS
 8.6 Synchronization 162
Synchronization to LDAP 162 ✦ Synchronization from LDAP 163
Bidirectional synchronization 166
8.7 Summary 167

9 Accessing operational information in LDAP 168

9.1 Getting server information 169
Retrieving available root naming contexts 169 ✦ Extracting object class
information 170 ✦ Getting attribute type details 174
9.2 Monitoring with LDAP 178
Getting the monitor’s name 178 ✦ Reading the monitor information 178
Polling the monitor entry 180
9.3 Testing replication 181
9.4 Summary 184

10 DSML: getting under the hood 185

10.1 DSML parsing with SAX 186
Basics of parsing XML with SAX 186 ✦ A simple XML parser handler 186
Parsing a simple document 188 ✦ PerlSAX’s built-in error checking 189
10.2 Parsing DSML into a Perl object 190
Beginnings of a useful DSML parser handler 192 ✦ Handling elements in
the DSML file 193 ✦ Extracting characters between start and end tags 194
Preparing to use DSMLHandler 194 ✦ Invoking the SAX parser using
DSMLHandler 194
10.3 Generating DSML 196
Writing directory entries 196 ✦ Converting RFC-style LDAP schemas to
DSML LDAP schemas 199 ✦ Conversion example for object classes 199
Converting attribute types 204
10.4 Using Perl to convert DSML with XSLT 208
Converting DSML to HTML 209
10.5 Summary 211

Part 3 Application integration 213

11 Accessing LDAP directories with JNDI 215
11.1 Introduction to JNDI 216
JNDI versus the LDAP Java SDK 216
11.2 JNDI architecture 216
JNDI providers 217 ✦ The JNDI package 217

CONTENTS ix
 11.3 JNDI operations: the DirContext class 217
Handling basic exceptions 218 ✦ Closing the connection 218
Binding to the directory 218 ✦ A reusable LDAP connection handler 219
11.4 Searching with JNDI 220
Abstracting the entry 221 ✦ A search class 223
11.5 Adding entries 226
A simple add example 226 ✦ A generalized add example 227
11.6 Manipulating entries 229
Modifying entries 229 ✦ Deleting entries 230 ✦ Renaming entries 231
11.7 Summary 232

12 Java programming with DSML 233

12.1 Writing DSML with Java 234
12.2 DSML with JNDI 235
Automatic DSML output from LDAP URLs 236
12.3 Working with schemas in DSML 237
Reading schemas with SAX 238 ✦ Designing a basic SAX handler 240
12.4 Transformation with XSLT in Java 244
12.5 Enhancements with DSMLv2 248
Implementing interapplication communication 249 ✦ Creating DSMLv2
SOAP requests 249 ✦ Creating DSMLv2 SOAP requests with JNDI 252
12.6 Summary 252

13 Application security and directory services 253

13.1 The relationship between security and directories 254
What is security? 254 ✦ How LDAP provides security 256
13.2 Storing key and certificate data 259
Preshared secret keys 259 ✦ Public/private key pairs 261
13.3 Using digital certificates 262
Creating a digital certificate in Java 263
Storing and distributing digital certificates 264
13.4 Managing authorization information 268
Understanding access control rules 268 ✦ Directory authorization 269
Application authorization 269
13.5 Encrypting LDAP sessions using JNDI and SSL 270
13.6 Summary 271

A: Standard schema reference 273

B: PerLDAP 302
index 317

x CONTENTS
preface
This book will help you understand and use the most important directory services—
those based on the leading industry standards—without having to read the many eso-
teric standards documents available on the Web. I am tempted to start the book with
a motivating example from my experience to explain why directory services are so
important and why you should read this book from cover to cover, but I will resist.
There is no need to tell a story from my experience, because I can tell a story from
your experience. Every single one of you has had experience with directory services,
whether you know it or not.
Did you log in to a computer today? When the computer checked your password,
it was probably using a directory service.
Do you use a personalized start page, such as Netscape Netcenter? If so, your pref-
erences and login information were found in a directory service and used to customize
your experience.
Have you ever looked up the email addresses of long-lost friends on the Internet,
or located the telephone number of the woman in receiving who can track down your
lost package? Both of these tasks are also common uses for directories.
However, you don’t need to learn how to type someone’s name into a search
engine or enter your password. What you do need to learn, and what this book will
teach you, is how to apply the standards that make directory services accessible over
computer networks ranging from the Internet to your corporate intranet to business
partners’ extranets.
We won’t stop there. The most pressing issue in the area of directory services today
is simply that there are so many of them. Every application written in the last 30 years
seems to have come with its own proprietary directory. Operating systems also have
directories. Most of these directories don’t care about each other or even acknowledge
the others’ existence. This book will help you get these existing directories to work well
with new, important standards-based directory services.
Finally, what good is a data repository without useful applications? If you are an
application developer trying to get your existing applications to work with Light-
weight Directory Access Protocol (LDAP), Directory Services Markup Language
(DSML), and other directory standards, this book not only will help you get a handle

xi
 on important application program interfaces (APIs), but also will deliver an under-
standing of the best strategies for using these applications to derive important appli-
cation benefits.

WHO AM I, AND WHAT’S MY MOTIVATION?

Many of the people picking up this book may know my reputation as a long-time
developer in the directory space. My background in this area includes writing the first
comprehensive Perl module for accessing directory services via LDAP, as well as writ-
ing software for getting applications such as Apache, the Squid proxy server, and
Cyrus mail servers to check passwords against servers supporting LDAP.
My recent work in this area has included the development of complete Java server
software for providing data via the LDAP protocol. The server, originally a part-time
open source project, is now the cornerstone of a virtual directory and proxy service
product offering from OctetString. However, this book is vendor neutral; all major
LDAP vendors are discussed to some extent in the first chapter.
Like many of you, I stumbled onto LDAP by accident. In 1993, I was employed
as part of Motorola’s Cellular Infrastructure Group in Arlington Heights, Illinois.
Along with a small group of other colleagues, I cofounded one of Motorola’s first web-
based intranets.
Unlike today, when most major web sites are dynamic and filled to the brim with
personalized content and real-time access to databases and important applications,
there were few web-based applications in those days. Sensing the potential use of this
new technology, yet realizing that this grass-roots project would not receive funding
if we couldn’t adequately expose business information, many team members pro-
ceeded to develop applications, such as card catalogs for engineering documents and
similar things.
I decided that my small project would be an email directory. As the only person
on this project from the IT organization, I was aware of a service provided by corporate
mainframes that presented information culled from human resources and local area
network (LAN) administrators over a simple protocol called WHOIS.
Using WHOIS, you could open a simple network connection to the server (which
in this case resided on a mainframe) and type the data to be used for searching. The
search results were returned as free-form text. My application did nothing more than
read this text, parse it, and write it out as HTML that could be displayed graphically
by a web browser.
It was an instant hit.
I became known at Motorola Cellular as the “directory” guy, and was instantly
pushed onto most of the projects that dealt with directories. At the time, these projects
primarily related to email. Email is an important use of directories—after all, if you
cannot locate the address of people with whom you need to communicate, a large email
infrastructure doesn’t do much good. However, I began to realize that this directory

xii PREFACE
 wasn’t just a way to look up information; it was a key storage point for identity infor-
mation—the only network-accessible place in the company where a person’s email
address, login ID, department, name, and manager were linked together. I realized that
smart applications could use this information to identify users throughout the com-
pany and authorize them based on criteria, such as their department. Those applica-
tions could also provide customized presentations based on that same information.
I also knew that as good as this idea was, it would be hard to execute given the lim-
itations of WHOIS, unless we customized each application. At this time, I came into
contact with X.500.
Like WHOIS, X.500 is a standard for a kind of directory service. Unlike WHOIS,
X.500 is anything but simple. It is a detailed set of standards definitions that seems
to describe everything within a 10-mile radius of directory services, including client
access, real security, server-to-server communications, and similar areas. Also unlike
WHOIS, X.500 comes from the OSI networking world, which was left in the dust in
the wake of the Internet explosion and the mass adoption of loosely networked systems
built around standards such as TCP/IP.
Nearly every book or article written about LDAP talks about X.500 being perfect
except for that dastardly OSI protocol stack, which makes deployment on desktop-
class hardware difficult. (Although there is truth to this reasoning, the real reason most
X.500 directory projects didn’t take off is that getting the right data into the directory
and keeping it up-to-date was difficult—after all, garbage in, garbage out. Similarly,
few applications were X.500 aware, partly due to its complexity.) This difficulty
spawned LDAP, which was meant to replace X.500’s Directory Access Protocol (DAP)
as a client implementation.
After making the move from X.500 to LDAP for the same published reasons every-
one else did, the lack of integration tools and directory-enabled applications was obvi-
ous. So, I created things like Net::LDAPapi and PerLDAP to glue together information
from different sources into the directory. Not long afterward, I wrote the code that
allowed users to be identified and authorized to many services, such as web, proxy,
and mail.
Today many applications are directory-enabled—so many that these applications
drive most new directory deployments, rather than the other way around. People look-
ing at deploying and accessing directories are faced with many difficult choices in
design and execution. My goal for this book is to help simplify this complex technol-
ogy in a way that accelerates your projects and improves your end results.

LESSONS LEARNED, AND THIS BOOK’S FOCUS

Since discovering LDAP, I’ve spent nearly every day looking to develop solutions to
these types of problems. Much of the time, the solution is centered on creating enter-
prise directory services. I’ve learned a few things about creating successful directory
services. The most critical are:

PREFACE xiii
 • Access is access.
• Configuration is trivial; management is complex.
Although these may seem like insanely simple lessons, let me explain.
Access is access
Certain methods of access may be more efficient or provide more underlying func-
tionality, but at the end of the day, it is only important that the directory service can
share information in a way that clients and applications can use. Today, that standard
for sharing information in directory services is LDAP. Therefore, we use LDAP as the
primary access protocol throughout this book.
However, many of the more advanced techniques described in parts 2 and 3 of this
book will work just as well with another means of access. In fact, part 3 describes the
use of Directory Services Markup Language (DSML), which you can use to represent
directory services information as XML.
Configuration is trivial; management is complex
This is not to say that your mother should be installing and configuring your direc-
tory servers. It is merely an indication of the relative complexity of configuration ver-
sus management.
I cannot stress enough that unless the directory is running in a stand-alone envi-
ronment where it is the only source of data, there will be effort in getting information
into and out of the directory. Unless you understand and make this effort up front,
the data in the directory will either be stale and useless or require yet another manual
administrative process to keep it up to date.
New technology is coming out that removes some of the technical barriers to splic-
ing information into authoritative directories. However, such technology does not
remove the internal political roadblocks and the need for up-front planning that is
required in nearly all meaningful directory service deployments.

xiv PREFACE
acknowledgments
Creating a quality technology book involves a great deal of effort from many talented
and passionate individuals. There is simply no way to thank all of those involved
enough for their efforts in making this book as good as it could possibly be.
I must start by thanking my wife Linda for her support in this endeavor. Without
her patience and strong support, this book certainly would never have been completed.
A few weeks before the book went to press, we received the special delivery of our son
Ethan, who was certainly an inspiration as the book’s development came to a close.
Too many people to name looked at bits and pieces of this book. Some of the peo-
ple who looked through early drafts were Kurt Zeilenga of the OpenLDAP project, La
Monte Yaroll of Motorola, Booker Bense of Stanford, Jay Leiserson and Richard
Goodwin of IBM, Jauder Ho of KPMG, Ranjan Bagchi, Juan Carlos Gomez and Raul
Cuza. Nathan Owen of IBM and Phil Hunt of OctetString also offered some very
helpful feedback on several key sections later in the development cycle.
Extra special thanks go to Booker Bense, who did a detailed final review of the
entire text and made a number of quality suggestions that I feel contributed to the
technical accuracy and readability of the book. Don Bowen of Sun was also especially
helpful in his review of key sections of the book as it neared completion.
Many people at Manning Publications were incredible throughout the process.
Marjan Bace and Mary Piergies were on top of this project with their full attention
and enthusiasm from the start. Lianna Wlasiuk was phenomenal as a development edi-
tor and offered many significant ideas that vastly improved the final content of the
book. Tiffany Taylor did a fantastic job of editing the text and removing all of the
embarrassing errors that I left behind. Dottie Marsico had the Herculean task of mak-
ing sense of a vast number of graphics in a myriad formats, among other things. Syd
Brown came up with the book’s wonderful design, and Leslie Haimes did a great job
putting together a captivating cover. Ted Kennedy did a masterful job of staying on
top of the entire review process.
Finally, a special thanks to everyone I’ve emailed or spoken with over the years
about this technology. These discussions helped shape much of the thinking that went
into this book. So much was learned from sharing information with the users of the
LDAP-related technology I’ve developed. This learning and interaction was truly a
reward for any effort on my part.

xv
about this book
Part 1 of the book has five chapters:
• Chapter 1 introduces core LDAP concepts, with the understanding that you may
have little or no past exposure to the protocol.
• Chapter 2 introduces LDAP’s information model and schema. Information in
an LDAP-enabled directory is presented in a simple and uniform way that you
should understand before proceeding. This chapter covers object classes,
attribute types, and schema standards.
• Chapter 3 offers information about LDAP namespace and naming standards.
Because all entries in LDAP are uniquely named, it’s important for you to
understand the information in this chapter.
• Chapter 4 provides an overview of LDAP search criteria. Because searching is
the most commonly used and most complex LDAP operation from a client per-
spective, we spend considerable time introducing and explaining filters, scope,
and search bases.
• Chapter 5 introduces the LDAP Data Interchange Format (LDIF) and the
Directory Services Markup Language (DSML), an XML standard for represent-
ing directory information, and shows how these standards can be used to easily
store and share directory information.
Part 2 is as follows:
• We begin exploring LDAP management in chapter 6. This chapter introduces the
Net::LDAP module, which lets you use Perl to access and manage an LDAP-
enabled directory.
• In chapter 7, we discuss administrative techniques. Examples include a web-
based tool that you can use to manage individual entries.
• Chapter 8 offers insights into synchronization and migration. No data exists in
a vacuum, so this chapter provides guidance about some of the ways data in
other directories and databases can be leveraged in an LDAP environment.

xvi
 • Chapter 9 explains how to monitor and manage information about the LDAP
server. Examples include schema retrieval scripts and tools for generating syn-
thetic transactions that can be used to check server availability.
• Chapter 10 expands on our previous discussion of DSML. Many examples are
provided, in Perl, including ones for generating DSML and transforming it to
HTML using XSLT.
Part 3 comprises the book’s final three chapters:
• In chapter 11, we begin discussing the best methods for directory-enabling your
applications. This chapter offers an introduction to the Java Naming and Direc-
tory Interface (JNDI), an API for accessing directory services based on many stan-
dards, including LDAP.
• In chapter 12, we refocus on DSML in an application context. Examples are
given that relate DSML to other technologies, such as web services and SOAP.
An exploration of DSML version 2 operations is also provided.
• Security ranks with messaging as a critical area for directory integration. For
that reason, we spend chapter 13 going over authentication, authorization, dig-
ital certificate storage, and LDAP security issues in general.
The book ends with two appendixes:
• Appendix A provides a compilation of standard schemas from Request for Com-
ments (RFCs), Internet Drafts, and other sources that you should consider prior
to the creation of new schemas. The LDAP schema is discussed in chapter 2.
• PerLDAP is a popular alternative to the Net::LDAP module discussed in part 2.
Appendix B offers an overview of PerLDAP and translation of many of the
examples in part 2.

WHO SHOULD READ THIS BOOK

This book is written for network and system administrators, as well as application
developers. Little or no past LDAP exposure is required.
Part 1 of this book uses command-line tools to demonstrate LDAP features. Part 2
provides examples in Perl that can be used unmodified in many cases or as the basis
for more advanced tools.
Finally, part 3 of the book is focused on application development issues with exam-
ples in Java. Although less directly useful to system and network administrators, it cov-
ers many important aspects of directory-enabled application development.

AUTHOR ONLINE
When you purchase LDAP Programming, Management and Integration you gain free
access to a private web forum run by Manning Publications where you can make

ABOUT THIS BOOK xvii

 comments about the book, ask technical questions, and receive help from the author
and from other users. To access the forum and subscribe to it, point your web
browser to www.manning.com/donley. This page provides information on how to get
on the forum once you are registered, what kind of help is available, and the rules of
conduct on the forum.
Manning’s commitment to our readers is to provide a venue where a meaningful
dialogue between individual readers and between readers and the author can take
place. It is not a commitment to any specific amount of participation on the part of
the author, whose contribution to the AO remains voluntary (and unpaid). We suggest
you try asking the author some challenging questions lest his interest stray!
The Author Online forum and the archives of previous discussions will be acces-
sible from the publisher’s web site as long as the book is in print.

SOURCE CODE
Source code for all examples presented in LDAP Programming, Management and
Integration is available for download from www.manning.com/donley.
Code conventions
Courier typeface is used for code examples. Bold Courier typeface is used in
some code examples to highlight important or changed sections. Certain references to
code in text, such as functions, properties, and methods, also appear in Courier
typeface. Code annotations accompany some segments of code.

xviii ABOUT THIS BOOK

getting started
Throughout this book, examples are provided wherever possible. This section details
where to get the tools you will need to use the examples.

DIRECTORY SERVERS
A directory server supporting LDAP is required to run these examples. The examples
should work with almost any LDAP-enabled directory server, except where noted
prior to the example.
This book is about getting the most from directory services, not installing and con-
figuring all the directories on the market. Following are pointers to some of the more
common directory servers available at the time of publication. Additionally, we
include basic instructions for obtaining a special LDAP server that has been precon-
figured to work with the examples in this book.
Directory server vendors
The LDAPZone (http://www.ldapzone.com) web site is a good place to begin when
you’re looking for answers to many directory issues. It has active community pages
and links to other sites related to LDAP. It also has links to the most popular LDAP
server implementations.
Among the servers currently listed are
• Novell eDirectory
• iPlanet Directory Server
• Oracle Internet Directory
• Critical Path InJoin Directory Server
• Microsoft Active Directory
• IBM SecureWay Directory
• Open Source OpenLDAP Directory
• Data Connection Directory
• OctetString Virtual Directory Engine

xix
 Each of these vendors provides a server that is directly LDAP accessible, with solid
documentation for installation and configuration.
Basic configuration parameters
The examples in this book assume the server will be listening on TCP port 389,
which is the standard LDAP port. This is usually easily configurable within the server,
although certain implementations (such as Microsoft Active Directory) cannot be
configured to listen on a different port.
The root of the directory tree used in the examples is dc=manning,dc=com.
This will be acceptable to most implementations, but some older servers may not be
aware of dc-style naming. If that is the case, substituting o=manning,c=us or any
other name for the root in configuration and examples should be acceptable. You can
find more information about naming and directory trees in chapter 3.
Most of the examples in this book use standard schemas related to people and
groups that can be found in virtually all LDAP implementations. If an example pro-
duces an error related to a schema violation, you may need to add the schema being
referenced by that example. Different directories have different files and configuration
options for adding new schemas.

COMMAND-LINE TOOLS
In part 1 of the book, no programming languages are used. Instead, we use com-
monly available LDAP tools to demonstrate key components of LDAP, such as infor-
mation model, entry naming, and search filters. These tools come with many
operating systems, such as Solaris and some Linux variants. They are also distributed
with many directory server products.
You can determine if the tools are available by attempting to run commands such
as ldapmodify and ldapsearch. If these commands exist, they should be suitable
for the examples in this book.
The source code to these tools can be found in at least two places:
• The OpenLDAP project (www.openldap.org)
• The Mozilla Directory project (www.mozilla.org/directory/)
Both of these versions are suitable for use with the examples in this book.
If you prefer to download precompiled versions of these tools, you can most easily
obtain them as part of the iPlanet Directory Software Development Kit (SDK). This
kit is available at http://www.iplanet.com/downloads/developer/.

LDAP PERL MODULES

Part 2 of this book, which focuses on directory management, uses the Perl language
to populate, synchronize, and otherwise manage information in directories. These
examples require a modern version of Perl (at least 5.005 is required, but 5.6 or

xx GETTING STARTED
 higher is recommended) and the Perl-LDAP module. This is not to be confused with
PerLDAP, which is the module previously released by Netscape and the author of this
book. Although both modules do the same job, Perl-LDAP is becoming more widely
used; and, because it is completely written in Perl, it is portable to any platform where
Perl is available.
The Perl-LDAP module is written and maintained by Graham Barr and can be
found at perl-ldap.sourceforge.net along with detailed installation instructions.
Active State Perl users can use these commands to install the necessary module
automatically:
C:\ >ppm
PPM interactive shell (2.1.6) - type 'help' for available commands.
PPM> install perl-ldap

Users of other versions of Perl can access the module on the Comprehensive Perl
Archive Network (CPAN) (http://www.cpan.org).

JAVA
Java is used extensively throughout part 3 of this book. We use core Java functional-
ity found in J2SE as well as extensions for communicating with LDAP and parsing
XML/DSML.

Java LDAP Access

There are two primary ways to access LDAP in Java:
• Java Naming and Directory Interface (JNDI)—You can use this generalized inter-
face to access LDAP and non-LDAP directory and naming services.
• Netscape Java SDK—This set of Java classes was created specifically to talk to
directory servers via the LDAP protocol.
This book uses JNDI. JNDI comes standard as part of Java development kits and
runtimes at or above the 1.3 version. It is available for download at java.sun.com for
earlier Java development kits.
DSML/XML
The examples in chapter 12 use both JNDI and the Java API for XML (JAXP). The
JNDI examples that read DSML files require the DSML provider for JNDI. This pro-
vider is a preview technology on java.sun.com at the time of publication. The JAXP
reference implementation from Sun is included with Java 1.4 and available for earlier
Java releases from Sun’s Java site at http://java.sun.com/.

GETTING STARTED xxi

about the cover illustration
The figure on the cover of LDAP Programming, Management and Integration is called
an “Aga de los Genizaros,” an officer in the Turkish infantry. The illustration is taken
from a Spanish compendium of regional dress customs first published in Madrid
in 1799. The title page of the Spanish volume states:
Coleccion general de los Trages que usan actualmente todas las Nacionas del Mundo des-
ubierto, dibujados y grabados con la mayor exactitud por R.M.V.A.R. Obra muy util y en
special para los que tienen la del viajero universal
which we translate, as literally as possible, thus:
General Collection of Costumes currently used in the Nations of the Known World,
designed and printed with great exactitude by R.M.V.A.R. This work is very useful espe-
cially for those who hold themselves to be universal travelers.
Although nothing is known of the designers, engravers, and workers who colored this
illustration by hand, the “exactitude” of their execution is evident in this drawing. It
is just one of many figures in this colorful collection. Their diversity speaks vividly of
the uniqueness and individuality of the world’s towns and regions just 200 years ago.
This was a time when the dress codes of two regions separated by a few dozen miles
identified people uniquely as belonging to one or the other. The collection brings to
life a sense of isolation and distance of that period and of every other historic period
except our own hyperkinetic present. Dress codes have changed since then and the
diversity by region, so rich at the time, has faded away. It is now often hard to tell the
inhabitant of one continent from another. Perhaps, trying to view it optimistically, we
have traded a cultural and visual diversity for a more varied personal life. Or a more
varied and interesting intellectual and technical life.
We at Manning celebrate the inventiveness, the initiative, and the fun of the com-
puter business with book covers based on the rich diversity of regional life of two cen-
turies ago brought back to life by the pictures from this collection.

xxii
 P A R T
1
Fundamental
LDAP concepts
The Lightweight Directory Access Protocol (LDAP) has emerged as the standard for
accessing directory services over networks. In this first part of the book, we will look
at everything you need to know about LDAP.
Chapter 1 begins with an exploration of the many uses and benefits of LDAP, as
well as its origin. From there we move on to an overview of current directory man-
agement and interoperability issues. At the end of chapter 1, we glance at the available
and emerging tools that allow for easier integration between different data sources.
Information is exchanged between LDAP clients and servers using containers called
entries. These containers are formed based on a particular information model that we
discuss in chapter 2.
Entries in a directory are given unique, hierarchical names in an LDAP directory.
In chapter 3, we look at how these names are formed, naming issues, and best practices.
Chapter 4 covers LDAP search criteria. The focus here is on simplifying the some-
times complicated combination of search filters, scopes, and bases that make up an
LDAP search request.
You will get your first look at Directory Services Markup Language (DSML), the
latest standard for representing directory information and operations in XML, in chap-
ter 5. Chapter 5 also formally introduces the LDAP Data Interchange Format (LDIF),
which is a commonly used format for sharing and storing directory information.
 C H A P T E R 1

Introduction to LDAP
1.1 What LDAP is 4 1.6 Directory management 23
1.2 What LDAP is not 7 1.7 Directory integration 24
1.3 Current applications 10 1.8 Integration and federation via virtual
1.4 Brief history 15 directory technology 30
1.5 LDAP revisions and other 1.9 Why this book? 31
standards 18 1.10 Summary 32

In this chapter, we introduce the Lightweight Directory Access Protocol (LDAP) and
attempt to answer the following questions:
• What is LDAP? Who needs it? How is it used?
• What are directory services? Where do they fit in the grand scheme of things?
Which ones exist? What is their relation to LDAP?
• What are common issues in planning and deploying directory services?
• Where do metadirectories, provisioning tools, and virtual directories fit
with LDAP?
• What standards organizations and industry consortia are responsible for further
development of directory services and LDAP standards?

3
Discovering Diverse Content Through
Random Scribd Documents
 Specific Character.

Shell turbinated, redish orange, with two undulated white

boards; base granulated, spire obtuse.
Conus lithoglyphus. Mus. Gevers. p. 350. Brug. Ency. Meth. p.
692. Lam. Syst. 7, 490. C. Ermineus, Dillwyn, 395.
Icones. Seba 3, pl. 42, f. 40, 41. Chem. pl. 140, f. 1298. Ency.
Meth. pl. 338, f. 8.? Martini, 2, pl. 57, f. 630.—1.?

The Cone Shells belong to a predatious race of Molluscæ, who feed

upon the innumerable "creeping things," which swarm in the prolific
seas of the Oriental hemisphere: destitute both of jaws and lips, their
mouth is formed into a long trunk or proboscis; with this they
contrive to bore into solid shells, and suck the vital juices of their
victims. Nearly all the species are natives of the Indian Ocean.

The circular system of Nature has been so fully demonstrated, that it

must now be received as the first great truth in Natural History. As,
therefore, there can be but one natural system, it necessarily follows
that all combinations of groups, whether large or small, which do not
pretend to exhibit such a disposition, must be more or less artificial
classifications. We allude to this our opinion, as explanatory of those
principles which have influenced the views indicated here of M.
Cuviers Pectinibranchi; the more so, as we shall be obliged to
characterize many new divisions, and to reform others, without the
immediate opportunity of explaining our reasons. In another work we
hope to enter on such details; and to shew we have been guided, in
this matter, by more weighty considerations than mere individual
opinion.

Pl. 66.
 TODUS viridis.
Green Tody.

T O D U S viridis.
Green Tody.

Family Todidæ. See Pl. 41.

Published Genera. Fluvicola. Nengetus. Alecturus. Muscicapa,

(pars). Conopophaga. Platyrhynchus. Todus. Eurylamus.
Querula? Psaris. Pachyrhynchus.

Generic Character. See Lesson, Man. 1, p. 178.

 Specific Character.

Bright green, beneath whiteish; throat scarlet; sides of the body

rosey; under tail covers yellow.
Todus viridis. Auct.

Mus. Paris. Nost.

This singular little bird has long excited the particular attention of
those naturalists who study the affinities of groups, more than the
details of species. It is a native of the West Indian Islands, and
although stated to be not uncommon, the accounts given of its
manners are perfectly contradictory. One author asserts that it is
almost always seen upon the ground, from whence it receives the
name of Perroquet de Terre: another, that it only frequents the
"lonely part of moist places" (woods?), where it sits in a couched
manner, with its head thrown considerably back, and is so stupid, as
almost to be taken by the hand. M. Vieillot confirms part of the latter
particulars, although he repeats, without denying, the former. In our
opinion the last is entitled to the most credance, although it is
contradictory to the idea of this being a terrestial bird.

We cannot but feel surprise and regret, that the "very interesting
account" of this bird, long ago announced (Zool. Journ. Dec. 1827. p.
439), as having been sent from Cuba, by Mr. Macleay, to the Linnean
Society, should still be unknown to the scientific world. There is,
indeed, a valuable paper by this gentleman on certain birds of Cuba,
in the first part of the sixteenth Vol. of the Society's Transactions,
where its author alludes to the "description and anatomy of two
birds" (p. 12) both of which are nevertheless omitted: The Todus
viridis, we apprehend is truly "one of those solitary species," which,
as Mr. Macleay observes, "from having been neglected, may serve to
unfold an exception, sufficient to destroy the most plausible system."
For ourselves, we shall feel much surprised if this bird is entitled, in
the slightest degree, to a station among the Fissirostres, in which
order it has been placed by M. Vigors, in his paper "On the Natural
affinities of Birds."

Pl. 67.
MURICINÆ Pl. 1.
Murex imperialis.

M U R E X Imperialis.
Imperial Murex.

Family, Buccinidæ. Sub-family Muricinæ. Nob.

Generic Character. See Lam. Syst.

Types of form. 1. M. Regius. 2. palmarosæ. 3. tripterus. 4.

tenuispinosus. 5. radix? Lam.
 Specific Character.

Type 1. Shell ponderous, with from four to five varices between

the two lips; the varices simple, nodulous, and obtuse:
intermediate, or false varices, none; aperture yellow, orange,
or red; inner lip striated only at the base.

The inhabitants of the Murices, or Rock Shells, are rapacious; and

feed, for the most part, upon animal matter, either living or dead. By
the latter instinct they are led to frequent harbours and sea-ports, for
the sake of offal, and other animal refuse, thrown from vessels,
which they greedily devour. Lamarck, with his usual precision, has
characterized many species; but for the very beautiful one now, we
believe, for the first time described, we have to thank Messrs.
Stuchbury, who favoured us with the inspection of a fine series of
specimens, received from the Island of Margarita, Lat. 11. 20. N. Lon.
63. 20. W.

The genera Buccinum and Murex of Linné, appear typical of the

carnivorous order Zoophaga, whose shells are either notched or
channelled at their base. These arrange themselves under two great
divisions. In one the animal has an operculum or lid, which closes the
entrance of his shell; in the other, the shell itself is more or less
enveloped by two large lobes, called the mantle, with which the
animal covers his habitation. Nevertheless, these two divisions, as M.
Cuvier has fully shown, become insensibly united, and form one
natural group. The two principal divisions of the operculated race are
represented by Cassis and Murex; the genera of the first have been
pretty correctly made out; but those of the Muricinæ require much
reformation; so far as regards the definition of their typical forms,
and their apparent series of affinities.
 Pl. 68.
CONUS. Pl. 1.
1. fumigatus. 2. franciscanus.

C O N U S fumigatus.

Family Strombidæ. Sub-family Conianæ.

Generic Character. See Lamarck.

Specific Character.

Shell smooth, spire very short, channeled, or with the whorls·

concave: colour chesnut, belted with white, and articulated
 rows of chesnut dots.
Conus fumigatus Brug. Diet. 94. Lam. Syst. 7. 496.
Icones. Mart. 2 pl. 56. f. 618. Ency. Meth. pl. 336. f. 7.

A species not conspicuous for its beauty, but by no means of

common occurrence: its close resemblance to the next has induced
us to illustrate both by figures. C. fumigatus seldom exceeds the size
here represented; it may at once be known from franciscanus (which
is a much smaller shell,) by the spiral whorls being concave, instead
of convex: this species occurs in the Indian Ocean.

If the student compares either Strombus Luhuanus, Mauritianus, or

Persicus, with any of the wide mouthed Cones, he will immediately
perceive the affinity between the two groups. In both, the operculum
of the animal is small, but in Conus it seems reduced to a mere
vestage; while the shell, nearly rolled upon its own axis, indicates the
near approach which Nature has now made towards the Cowries; a
family, however, essentially distinguished by the great developement
of the mantle, and the total absence of an operculum.

C O N U S franciscanus.
Shell smooth, chesnut, with two white bands, the upper one near
the suture: spire short, the whorls convex.
C. franciscanus. Lam. Syst. 7. 493. Ency. Meth. 337. f. 5.

Lamarck mentions Africa and the shores of the Mediterranean, as the

native locality of this shell. It escaped our researches on the coasts of
Italy, Sicily, and Greece, and we suspect it to be an Oriental species.

Pl. 69.
PIERIS Nigrina.

P I E R I S Nigrina.

Pieris (pars.) Latr: Stev. Pontia (pars.) Fab. Horsf.

Generic Character.

Antennæ with a spatulate, considerably compressed, obovate

club. Palpi hairy: the first joint with basal articulations, (Horsf.
pl. 4. f. 10) beyond which it is hardly longer than the second,
 or the third, which are each of equal length. Anterior Wings
with the exterior margin manifestly shorter than the posterior.

Type. Pieris Belisama. Lat.

Specific Character.

Wings above white in one sex, grey in the other; anterior tipt
with black; beneath black, with a terminal band of yellow:
posterior wings beneath black, varied with grey, and marked
with an undulated, nearly central, border of crimson.
Pieris Nigrina. Fab. Sys. Ent. 475. Ent. Sys. 3. 1. 20. Ency. Meth.
p. 149. Don. Ins. of New Holl. 19. f. 1.

Although this elegantly marked insect has long been known to

Entomologists, we believe it has only once been figured. It is not
uncommon in Australia, and being a typical species, we select it to
illustrate this group.

The Butterflies called Whites, in the common language of Collectors,

(Pieris, Lat.) are distinguished by their great simplicity of colouring,
and a predominence of white upon their wings. It is a singular fact,
that the various species of this family, among which are included the
different white Butterflies of Europe; feed chiefly on such plants as
are nourishing and salutary to the human body, such as the various
sorts of cabbages, coleworts, turnips, &c., and in every foreign
country where these white Butterflies have been found, plants of the
same nutricious qualities, are sure to be discovered in the vicinity of
their haunts.
The group to which we here restrict the name of Pieris, is confined,
we believe, exclusively to the old world, and principally to
intertropical latitudes. We have been much embarassed, however, in
applying this name correctly. Dr. Horsfield has placed many of our
Indian Pieres under the genus Pontia, which group is restricted by Mr.
Stephens to European insects. As this latter disposition is more in
unison with our own views, we have adapted it; considering P.
Cratægi to be the only aberrant representative of Pieris in Europe.

Pl. 70.
EURYMUS Europome.

E U R Y M U S Europome.
The Clouded Sulphur.
 Generic Character. See Pl. 60.

Specific Character.

See Stevens. Ill. of Brit. Ent. 1. p. 10. and Haw. Lep. Brit. 13.
Papilio Europome. Haworth Lep. Brit. p. 13. No. 12.
Colias Europome. Stev. pl. 1.* fig. 1. male. 2. 3. female. Syst.
Cat. 5797.

In Mus. Nost.

Much interest has recently been excited among British entomologists

regarding this butterfly. Some are of opinion that it is not a native of
Britain, while others, with a strong shew of reason, contend that it is
truly indiginous. The specimens in the British collection formed by our
lamented parent, and now in our possession, having been alluded to
by both parties, we have been induced to represent them, and to
throw some light upon their history.

So anxiously did our honored father preserve his cabinet, free from
exotic specimens, that knowingly, he never admitted one, even as a
temporary substitute for a native example. Yet living, in his early
days, in constant intercourse with the famous Dutchess of Portland,
Dr. Lightfoot, and Mr. Lewin, he received, from these sources, some
few insects, which were placed in his cabinet, under the assurance
that they were British. Among these are Pap. Podalirius, Daplidice,
and the two specimens of the alleged Europome here figured: the
latter being mistaken, and intermixed, with three examples of the
true Hyale. On the other hand, it is incumbent upon us to say, that
both these have been mended, before coming into our father's
possession, by the heads and antennae of Gonepteryx Rhamni! We
must also state, that upon closely comparing them with a series of E.
Philodice, we have failed to discover what appears to us a true
specific distinction. The same unsuccess has attended our efforts to
detach Chrysotheme from Edusa, of which latter we possess
specimens from Germany, Genoa, Sicily, Greece, Africa, and several
others unlabelled, all varying more or less from each other, and from
British examples.

Pl. 71.
MALACONOTUS Barbarus.
Barbary Shrike.

M A L A C O N O T U S Barbarus.
Barbary, or yellow-crowned Shrike.
 Family Laniadæ. Sub-family Thamnophilinæ. Nob.

Generic Character.

Swains. in Zool. Journ. 3. p. 163.

Specific Character.

Above glossy black, beneath crimson; crown fulvous yellow: vent

and flanks buff.
Lanius barbarus. Linn. Icon. Pl. Enl. 56.
Laniarius barbarus. Ency. Meth. Orn. p. 755.
Le Gonolek. Le Vaill. Ois. d'Af. pl. 69.

The true Shrikes, of which two, if not three species inhabit England,
are bold and cruel birds: they attack others, scarcely smaller than
themselves, and seize them like a Falcon, by their talons during flight.
The Bush Shrikes on the other hand, are a more ignoble race; they
only prowl after young or sickly birds, and seek their principal
nourishment from those insects which shelter in foliage. These birds
form two distinct groups, confined to the tropical latitudes of the Old
and the New World. The first, Thamnophilus, is restricted to America,
and the species are known by their dark coloured plumage.
Malaconotus, is, we believe, purely an African group, while most of
the typical species, like the present, are cloathed in bright and
beautiful colours.

This elegant bird seems to be abundant in Western Africa, but is rare

towards the Cape of Good Hope. Hence Le Vaillant had no
opportunity of learning its peculiar manners. Its size is that of a
Thrush; the feathers on the back are very long, and the first joint of
the outer toe is free. Nature, ever prone to typify her relations, and
to preserve harmony between groups, essentially distinct, has given
to the bill of this bird, a form closely resembling that of Pitta; the
genus by which Malaconotus is represented among the Thrushes.

A partial consideration of this group induced us, some years ago, to

adopt the generic name of Laniarius; but in a more recent
investigation of the species so denominated, we have failed to
discover sufficient reason for separating them, generically, from
Malaconotus.

Pl. 72.
DONACOBIUS vociferans.
Babbling Thrush.
 D O N A C O B I U S vociferans.
Babbling Thrush.

Family Merulidæ. Sub-family Macropodianæ. Nob.

Characters.

Bill arched from the base, moderate, and generally entire; wings
very short: tail broad, rounded. Feet and toes of great strength
and size; plumage lax, and soft. Nobis.
Gracula (pars.) Cuv. Pomatorhinus. Horsf. Tem. (pars.) Pitta. (p.)
Opetiorhynchus. Ixos. (p.) Malurus (p.) Tem. Timalia. Megalurus.
Horsf. Dasyornis. Phosphodes. Vig.

Generic Character.

Bill slender, moderate, the upper mandible notched; nostrils

naked, membranaceous, the aperture terminal.

Specific Character.

Above blackish brown, beneath fulvous yellow; sides of the body

lineated with black lines, base of the quills and tips of the
laternal tail feathers pure white, sides of the neck, with a
naked space.
Gracula longirostris? Auct.
It is seldom that the notes of the feathered race are absolutely
disagreeable, but we never remember to have heard a bird with a
voice of such astounding discord, as that now before us. Its particular
note, if note it could be called, we do not now recollect; but it was so
shrill, grating, and monotonous, that we have frequently rushed out
of the house, to drive away the babbling disturbers. This happened at
the hospitable residence of our friend Mr. Pinches, of Pernambucco,
whose house was close to a small swamp, overgrown with reeds,
among which these birds delight to dwell; and which in fact, they
never quit. Clinging to the smooth stems by their strong feet and
acute claws, they were incessantly uttering discord with the most
provoking perseverance: all the time moving their body from one side
to the other, spreading out their tail, and straining their throats, in
the most grotesque way imaginable. On each side of the neck, is a
long space of bare skin of a deep yellow colour: they live in pairs,
and build a pensile nest among the reeds: their flight is very slow and
feeble.

Pl. 73.
MURICINÆ. Pl. 2.
Murex erythrostomus.
 M U R E X erythrostomus.
Pink-mouthed Murex.

Family Buccinidæ. Sub-family Muricinæ. Nob.

Specific Character.

(Type 1.) Shell spinous: varices between the two lips four; armed
with conic, generally pointed spines, the upper and lower of
which are vaulted; colour reddish white, articulated with
brown: false varices intermediate; aperture rosey: inner lip
smooth.

Messrs. Stuchbury obligingly forwarded us fine specimens of this

lovely species, for comparison with M. Regius and Imperialis. In
general habit it has a close affinity to the first, but is distinguished by
intermediate false varices, which in that species are wanting; while
the upper and lower spines are alone vaulted: from Imperialis our
shell is further removed, by the varices being spinous, instead of
nodulous; this latter character being seen only in the intermediate
protuberances, and in the false varices.

We have already intimated our belief that Murex and Cassis represent
two equivalent groups; and these, as containing several established
genera, we shall consider as sub-families: giving them the usual
termination of inæ. Those higher naturalists, who have long since
abandoned the belief in absolute divisions and isolated genera, are
fully aware that no groups are more likely to exhibit the arrangement
of nature, than such as contain numerous species, under a great
diversity of forms. The Murices are of this description, and appear to
exhibit, among themselves, a circular series. Triton and Murex also
seem typical genera, and of equal value. Ranella obviously belongs to
the first; yet, as it is merely a subordinate type of form, we cannot,
under this belief, retain it as a genus, without a manifest
inconsistency; unless, indeed, it is thought expedient to consider the
types of form in Murex, as so many genera, and elevate three others
in Triton to the same rank; a refinement in nomenclature, which we
cannot think is in the least degree necessary.

Pl. 74.
EUTERPE Terea.

E U T E R P E Terea.
 Papilio. (pars.) Latrielle. Sub-family Pieresinæ. Nob.

Generic Character.

Antennæ lengthened, terminating in a broad, very compressed,

spatulate club. Palpi hairy; the first joint very long, exceeding
the united length of the two next: second joint half as long as
the first; third very small, manifestly shorter than the second.
Anterior wings long, papilioniform; the exterior margin longer
than the posterior. Nob.

Specific Character.

Wings above black: anterior both above and below, with a trifid
white or yellowish central spot: posterior with a four-parted
rosey spot; and varigated beneath, at the base, with yellow
and rosy stripes.
Papilio Terias. Latrielle & Godart. En. Meth. 1. p. 38. No. 39.

Nature has so completely disguised this Butterfly in the form and

colours of a genuine Papilio, as to have deceived the first
entomologist now in Europe, and his most skilful and accurate
coadjutator. In the Ency. Methodique we find this species recorded as
a Papilio; whereas it perfectly agrees, in all the details of its structure,
with the characters proposed in that valuable work for the genus
Pieris. Whether nature has employed this beautiful device to indicate
the group which next succeeds in her series, or whether she has
intended it to point out a strong analogy, are questions which, in our
present imperfect knowledge of Lepidopterous groups, cannot be
answered.
Of this group we possess several new and highly interesting species.
It is worthy of remark, that they were all collected in one particular
locality, and at the same season. This was during a short residence at
Mandioca, the plantation of Dr. Langsdorff, among the woods at the
base of the Organ mountains, near Rio de Janeiro.

We believe this group is restricted to tropical America, where it

probably represents the genuine Pieres, (as defined at pl. 69,) of the
Old World. The present species is subject to much variation in the
size, proportion, and colour of its spots: the white is sometimes pale
yellow, and the rosy becomes of a deeper and brighter hue.

Pl. 75.
PELEUS.
1. Gentius. 2. Æacus

P E L E U S Æacus.
 Family Hesperidæ.

Generic Character.

Antennæ not hooked, the club formed into a long, slender,

fusiform arch. Wings with both surfaces alike, horizontally
divaricated when at rest; posterior rounded, entire; broader
from the base to the anal angle, than to the exterior margin.

Type. Hesp. Peleus. Fab.

Specific Character.

Wings deep brownish black; anterior with a redish transverse

band, united to a spot of the same, and tipt with a sub-hyaline
band of redish orange.
Hesp. Peleus. Fab. Cramer, pl. 284, f. F.

Entomologists, from being acquainted only with the habits of the

European species of this family, represent the Hesperidæ as resting
with only the hinder wings elevated: This is altogether a mistake.
Some groups, indeed, assume this position when basking in the sun,
or taking food; but even these, when fairly at rest, erect their wings
in the ordinary manner: a fact we have repeatedly witnessed. Not so,
however, with the group we now illustrate: and which is peculiar to
South America. These insects rest with all the four wings expanded;
and hide themselves during the meridian heat, on the under side of
broad leaves, in the deep forests. From never appearing exposed,
this species long escaped our search, but having once discovered this
singular part of its economy, we captured it in abundance. It probably
feeds, like many of the Sphingides, or Hawk Moths, in the morning
and evening, but its haunts were too far from our habitation, to allow
of ascertaining this point.

P E L E U S Gentius.
Anterior wings black, with three yellow bars, posterior yellow,
with a simple black border.
Hesp. Gentius. Fab. Cramer, pl. 179, f. C.

Our specimens of this very rare insect were captured by Dr.

Langsdorff, in the interior of Southern Brazil, the colours of the under
surface of the wings are the same as those of the upper.

Pl. 76.
MALACONOTUS atro-coccineus.
Black & crimson Shrike.
Welcome to our website – the ideal destination for book lovers and
knowledge seekers. With a mission to inspire endlessly, we offer a
vast collection of books, ranging from classic literary works to
specialized publications, self-development books, and children's
literature. Each book is a new journey of discovery, expanding
knowledge and enriching the soul of the reade

Our website is not just a platform for buying books, but a bridge
connecting readers to the timeless values of culture and wisdom. With
an elegant, user-friendly interface and an intelligent search system,
we are committed to providing a quick and convenient shopping
experience. Additionally, our special promotions and home delivery
services ensure that you save time and fully enjoy the joy of reading.

Let us accompany you on the journey of exploring knowledge and

personal growth!

ebookname.com