We're pleased to announce version 0.0.2 of Net::LDAP, the first
pure-Ruby LDAP library. Net::LDAP intends to be a feature-complete
LDAP client which can access as much as possible of the functionality
of the most-used LDAP server implementations. This library does
not wrap any existing native-code LDAP libraries, creates no
Ruby extensions, and has no dependencies external to Ruby.

Version 0.0.2 includes an implementation of the "paged search
control" to enable queries of A/D result sets > 1000 entries.
It also fills in some holes in the documentation.

We fixed a handful of issues that gave strange-looking errors when
working with A/D. The most important of these was support for search
referrals.

Net::LDAP now works with standard RFC-2254 filter strings (see
Net::LDAP::Filter#construct). This is intended as an adjunct to
(not a replacement for) the existing Filter API, which is considerably
easier to use for people who are not LDAP experts.

We added a range of new APIs, and deprecated some existing ones.
The goal is to make the Net::LDAP API as intuitive and Ruby-like
as possible. We'll be adding more improvements to the API as we
go along.

Please note that Net::LDAP is licensed under the Ruby license
or LGPL, at your option. (I'm saying it publicly right here!)
There are still many source files in the distro that contain
GPL verbiage. We will clean that up in a future release.

And finally we fixed the annoying problem that the 0.0.1 gem
and tarball had trailing garbage. Thanks to Austin for helping
track that down. Thanks also to Andre Nathan and others for
several valuable suggestions and notes on your experience with
the library.

Progress so far: Net::LDAP is now in use on a variety of production
sites. Stability has been excellent, and performance is quite good.
We've found by far that the most popular application is authentication
for users of web sites, but there has been some chatter about
authorization as well, and a few of you are building directory-enabled
applications.

= What's next on the roadmap?

Many of you have requested support for encryption. We will soon be
adding support for STARTTLS and LDAPS to Net::LDAP, using Ruby's
built-in OpenSSL library.

We'd like to improve the API so it presents a more search-like interface
and further masks the archaic (and arcane) native LDAP vocabulary.

We have a project going ("Peregrine") to provide a full-featured
LDAP server in Ruby, based on the EventMachine fast network-IO library,
that you can use with your own Ruby classes. This will allow you
to serve LDAP clients (such as mailers, IM, and calendaring apps) with data
that you generate dynamically from your own code.

Finally, we've started thinking about an authentication generator or
plugin for Rails that will work against LDAP servers. It would be even
more interesting to augment it with fine-grained authorization at the
controller level.

If anyone wants to contribute suggestions, insights or (especially)
code, please email me at garbagecat10@gmail.com.

= What is Net::LDAP for Ruby?
This library provides a pure-Ruby implementation of an LDAP client.
It can be used to access any server which implements the LDAP protocol.

Net::LDAP is intended to provide full LDAP functionality while hiding
the more arcane aspects of the LDAP protocol itself, so as to make the
programming interface as Ruby-like as possible.

In particular, this means that there is no direct dependence on the
structure of the various "traditional" LDAP clients. This is a ground-up
rethinking of the LDAP API.

Net::LDAP is based on RFC-2251, which specifies the Lightweight Directory
Access Protocol, as amended and extended by subsequent RFCs and by the more
widely-used directory implementations.

Homepage::  http://rubyforge.org/projects/net-ldap/
Download::  http://rubyforge.org/frs/?group_id=143
Copyright:: 2006 by Francis Cianfrocca

== LICENCE NOTES
Please read the file LICENCE for licensing restrictions on this library. In
the simplest terms, this library is available under the same terms as Ruby
itself.

== Requirements and Installation
Net::LDAP requires Ruby 1.8.2 or better.

Net::LDAP can be installed with:

 % ruby setup.rb

Alternatively, you can use the RubyGems version of Net::LDAP available
as ruby-net-ldap-0.0.2.gem from the usual sources.

== Whet your appetite:
    require 'net/ldap'
    
    ldap = Net::LDAP.new :host => server_ip_address,
         :port => 389,
         :auth => {
               :method => :simple,
               :username => "cn=manager,dc=example,dc=com",
               :password => "opensesame"
         }
  
    filter = Net::LDAP::Filter.eq( "cn", "George*" )
    treebase = "dc=example,dc=com"
    
    ldap.search( :base => treebase, :filter => filter ) do |entry|
      puts "DN: #{entry.dn}"
      entry.each do |attribute, values|
        puts "   #{attribute}:"
        values.each do |value|
          puts "      --->#{value}"
        end
      end
    end
    
    p ldap.get_operation_result

== Net::LDAP 0.0.2: May 3, 2006
* Fixed malformation in distro tarball and gem.
* Improved documentation.
* Supported "paged search control."