ruby-activeldap 0.4.1

data/lib/activeldap.rb

@@ -0,0 +1,889 @@
+#!/usr/bin/ruby -W0
+# = Ruby/ActiveLDAP 
+#
+# "Ruby/ActiveLDAP" Copyright (C) 2004 Will Drewry mailto:will@alum.bu.edu
+# Documentation Version 0.3
+#
+# == Introduction
+# 
+# Ruby/ActiveLDAP is a novel way of interacting with LDAP.  Most interaction with
+# LDAP is done using clunky LDIFs, web interfaces, or with painful APIs that
+# required a thick reference manual nearby. Ruby/ActiveLDAP aims to fix that.
+# Inspired by ActiveRecord[http://activerecord.rubyonrails.com], Ruby/ActiveLDAP provides an
+# object oriented interface to LDAP entries.
+# 
+# The target audience is system administrators and LDAP users everywhere that
+# need quick, clean access to LDAP in Ruby.
+# 
+# === What's LDAP?
+# 
+# LDAP stands for "Lightweight Directory Access Protocol." Basically this means
+# that it is the protocol used for accessing LDAP servers.  LDAP servers
+# lightweight directories.  An LDAP server can contain anything from a simple
+# digital phonebook to user accounts for computer systems.  More and more
+# frequently, it is being used for the latter.  My examples in this text will
+# assume some familiarity with using LDAP as a centralized authentication and
+# authorization server for Unix systems. (Unfortunately, I've yet to try this
+# against Microsoft's ActiveDirectory, despite what the name implies.)
+# 
+# Further reading: 
+# * RFC1777[http://www.faqs.com/rfcs/rfc1777.html] - Lightweight Directory Access Protocol
+# * OpenLDAP[http://www.openldap.com]
+# 
+# === So why use Ruby/ActiveLDAP?
+# 
+# Well if you like to fumble around in the dark, dank innards of LDAP, you can
+# quit reading now.  However, if you'd like a cleaner way to integrate LDAP in to
+# your existing code, hopefully that's why you'll want to use Ruby/ActiveLDAP.
+# 
+# Using LDAP directly (even with the excellent Ruby/LDAP), leaves you bound to
+# the world of the predefined LDAP API.  While this API is important for many
+# reasons, having to extract code out of LDAP search blocks and create huge
+# arrays of LDAP.mod entries make code harder to read, less intuitive, and just
+# less fun to write.  Hopefully, Ruby/ActiveLDAP will remedy all of these
+# problems!
+# 
+# == Getting Started
+# 
+# Ruby/ActiveLDAP does have some overhead when you get started.  You must not
+# only install the package and all of it's requirements, but you must also make
+# customizations that will let it work in your environment.
+# 
+# === Requirements
+# 
+# * Ruby[http://www.ruby-lang.com] 1.8.x
+# * Ruby/LDAP[http://ruby-ldap.sourcefcome.net]
+# * Log4r[http://log4r.sourcefcome.net]
+# * (Optional) Ruby/LDAP+GSSAPI[http://caliban.com/files/redhat/RPMS/i386/ruby-ldap-0.8.2-4.i386.rpm]
+# * An LDAP server compatible with Ruby/LDAP: OpenLDAP[http://www.openldap.com], etc
+#   - Your LDAP server must allow root_dse queries to allow for schema queries
+# * Examples also require: Ruby/Password[http://raa.ruby-lang.com/project/ruby-password/]
+# 
+# === Installation
+# 
+# Assuming all the requirements are installed, you can install by grabbing the latest tgz file from
+# the download site[http://projects.example.com/libraries/ruby/activeldap/download.html].
+# 
+# The following steps will get the Ruby/ActiveLDAP installed in no time!
+# 
+#   $ tar -xzvf ruby-activeldap-current.tgz
+#   $ cd ruby-activeldap-VERSION
+# 
+# Edit lib/activeldap/configuration.rb replacing values to match what will work
+# with your LDAP servers. Please note that those variables are required, but can
+# be overridden in any program  as detailed later in this document. Also make
+# sure that "ROOT" stays all upcase.
+# 
+# Now run:
+# 
+#   $ ruby setup.rb config
+#   $ ruby setup.rb setup
+#   $ (as root) ruby setup.rb install
+# 
+# Now as a quick test, you can run:
+# 
+#   $ irb
+#   irb> require 'activeldap'
+#   => true
+#   irb> exit
+# 
+# If the require returns false or an exception is raised, there has been a
+# problem with the installation.  You may need to customize what setup.rb does on
+# install.
+# 
+# 
+# === Customizations
+# 
+# Now that Ruby/ActiveLDAP is installed and working, we still have a few more
+# steps to make it useful for programming.
+# 
+# Let's say that you are writing a Ruby program for managing user and group
+# accounts in LDAP. I will use this as the running example throughout the
+# document.
+# 
+# You will want to make a directory called 'ldapadmin' wherever is convenient. Under this directory,
+# you'll want to make sure you have a 'lib' directory.
+# 
+#   $ cd ~
+#   $ mkdir ldapadmin
+#   $ cd ldapadmin
+#   $ mkdir lib
+#   $ cd lib
+# 
+# The lib directory is where we'll be making customizations. You can, of course,
+# make this changes somewhere in Ruby's default search path to make this
+# accessible to every Ruby scripts. Enough of my babbling, I'm sure you'd like to
+# know what we're going to put in lib/.
+# 
+# We're going to put extension classes in there. What are extension classes you say . . .
+# 
+# 
+# == Usage
+# 
+# This section covers using Ruby/ActiveLDAP from writing extension classes to
+# writing applications that use them.
+# 
+# Just to give a taste of what's to come, here is a quick example using irb:
+# 
+#   irb> require 'activeldap'
+# 
+# Here's an extension class that maps to the LDAP Group objects:
+# 
+#   irb> class Group < ActiveLDAP::Base
+#   irb* ldap_mapping
+#   irb* end
+# 
+# Here is the Group class in use:
+# 
+#   irb> all_groups = Group.find_all('*')
+#   => ["root", "daemon", "bin", "sys", "adm", "tty", ..., "develop"]
+#  
+#   irb> group = Group.new("develop")
+#   => #<Group:0x..........>
+#  
+#   irb> group.members
+#   => ["drewry"]
+#  
+#   irb> group.cn
+#   => "develop"
+# 
+#   irb> group.gidNumber
+#   => "1003"
+# 
+# That's it! No let's get back in to it.
+#
+# === Extension Classes
+# 
+# Extension classes are classes that are subclassed from ActiveLDAP::Base.  They
+# are used to represent objects in your LDAP server abstractly.
+# 
+# ==== Why do I need them?
+# 
+# Extension classes are what make Ruby/ActiveLDAP "active"! They do all the
+# background work to make easy-to-use objects by mapping the LDAP object's
+# attributes on to a Ruby class.
+# 
+# 
+# ==== Special Methods
+# 
+# I will briefly talk about each of the methods you can use when defining an
+# extension class.  In the above example, I only made one special method call
+# inside the Group class. More than likely, you will want to more than that.
+# 
+# ===== ldap_mapping
+# 
+# ldap_mapping is the only required method to setup an extension class for use
+# with Ruby/ActiveLDAP. It must be called inside of a subclass as shown above.
+# 
+# Below is a much more realistic Group class:
+# 
+#   class Group < ActiveLDAP::Base
+#     ldap_mapping :dnattr => 'cn', :prefix => 'ou=Groups', :classes => ['top', 'posixGroup']
+#   end
+# 
+# As you can see, this method is used for defining how this class maps in to LDAP.  Let's say that 
+# my LDAP tree looks something like this:
+# 
+#   * dc=example,dc=com
+#   |- ou=People,dc=example,dc=com
+#   |+ ou=Groups,dc=example,dc=com
+#     \
+#      |- cn=develop,ou=Groups,dc=example,dc=com
+#      |- cn=root,ou=Groups,dc=example,dc=com
+#      |- ...
+# 
+# Under ou=People I store user objects, and under ou=Groups, I store group
+# objects.  What |ldap_mapping| has done is mapped the class in to the LDAP tree
+# abstractly. With the given :dnattr and :prefix, it will only work for entries
+# under ou=Groups,dc=example,dc=com using the primary attribute 'cn' as the
+# beginning of the distinguished name.
+# 
+# Just for clarity, here's how the arguments map out:
+# 
+#   cn=develop,ou=Groups,dc=example,dc=com
+#   ^^         ^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
+#  :dnattr       |         |
+#              :prefix     |
+#                :base from configuration.rb
+# 
+# 
+# Something's missing: :classes.  :classes is used to tell Ruby/ActiveLDAP what
+# the minimum requirement is when creating a new object. LDAP uses objectClasses
+# to define what attributes a LDAP object may have. Ruby/ActiveLDAP needs to know
+# what classes are required when creating a new object.  Of course, you can leave
+# that field out to default to ['top'] only.  Then you can let each application
+# choose what objectClasses their objects should have by calling the method e.g.
+# Group#objectClass=(value).
+# 
+# :classes isn't the only optional argument.  If :dnattr is left off, it defaults
+# to 'cn'.  If :prefix is left off, it will default to 'ou=CLASSNAME'. In this
+# case, it would be 'ou=Group'.
+# 
+# :classes should be an Array. :dnattr should be a String and so should :prefix.
+# 
+# 
+# ===== belongs_to
+# 
+# This method allows an extension class to make use of other extension classes
+# tying objects together across the LDAP tree. Often, user objects will be
+# members of, or belong_to, Group objects.
+# 
+#   * dc=example,dc=com
+#   |+ ou=People,dc=example,dc=com
+#    \
+#    |- uid=drewry,ou=People,dc=example,dc=com
+#   |- ou=Groups,dc=example,dc=com
+# 
+# 
+# In the above tree, one such example would be user 'drewry' who is a part of the
+# group 'develop'. You can see this by looking at the 'memberUid' field of 'develop'.
+# 
+#   irb> develop = Group.new('develop')
+#   => ...
+#   irb> develop.memberUid
+#   => ['drewry', 'builder']
+# 
+# If we look at the LDAP entry for 'drewry', we do not see any references to
+# group 'develop'. In order to remedy that, we can use belongs_to
+# 
+#   irb> class User < ActiveLDAP::Base
+#   irb*   ldap_mapping :dnattr => 'uid', :prefix => 'People', :classes => ['top','account']
+#   irb*   belongs_to :groups, :class_name => 'Group', :foreign_key => 'memberUid', :local_key => 'uid'
+#   irb* end
+# 
+# Now, class User will have a method called 'groups' which will retrieve all
+# Group objects that a user is in.
+# 
+#   irb> me = User.new('drewry')
+#   => ...
+#   irb> me.groups
+#   => ["cdrom", "audio", "develop"]
+# 
+# Methods created with belongs_to also take an optional argument: objects. This
+# argument specifies whether it will return the value of the 'dnattr' of the
+# objects, or whether it will return Group objects.
+# 
+#   irb> me.groups(true)
+#   => [#<Group:0x000001 ...>, #<Group:0x000002 ...>, ...]
+#   irb> me.groups(true).each { |group| p group.cn };nil
+#   "cdrom"
+#   "audio"
+#   "develop"
+#   => nil
+# 
+#   (Note: nil is just there to make the output cleaner...)
+# 
+# TIP: If you weren't sure what the distinguished name attribute was for Group,
+# you could also do the following:
+# 
+#   irb> me.groups(true).each { |group| p group.dnattr };nil
+#   "cdrom"
+#   "audio"
+#   "develop"
+#   => nil
+# 
+# Now let's talk about the arguments.  The first argument is the name of the
+# method you wish to create. In this case, we created a method called groups
+# using the symbol :groups. The next collection of arguments are actually a Hash
+# (as with ldap_mapping). :class_name should be a string that has the name of a
+# class you've already included. If you class is inside of a module, be sure to
+# put the whole name, e.g. :class_name => "MyLdapModule::Group". :foreign_key
+# tells belongs_to what attribute Group objects have that match the :local_key.
+# :local_key is the name of the local attribute whose value should be looked up
+# in Group under the foreign key. If :local_key is left off of the argument list,
+# it is assumed to be the dnattr. With this in mind, the above definition could
+# become:
+# 
+#   irb> class User < ActiveLDAP::Base
+#   irb*   ldap_mapping :dnattr => 'uid', :prefix => 'People', :classes => ['top','account']
+#   irb*   belongs_to :groups, :class_name => 'Group', :foreign_key => 'memberUid'
+#   irb* end
+# 
+# In addition, you can do simple membership tests by doing the following:
+# 
+#   irb> me.groups.member? 'root'
+#   => false
+#   irb> me.groups.member? 'develop'
+#   => true
+# 
+# ===== has_many
+# 
+# This method is the opposite of belongs_to. Instead of checking other objects in
+# other parts of the LDAP tree to see if you belong to them, you have multiple
+# objects from other trees listed in your object. To show this, we can just
+# invert the example from above:
+# 
+#   class Group < ActiveLDAP::Base
+#     ldap_mapping :dnattr => 'cn', :prefix => 'ou=Groups', :classes => ['top', 'posixGroup']
+#     has_many :members, :class_name => "User", :local_key => "memberUid", :foreign_key => 'uid'
+#   end
+# 
+# Now we can see that group develop has user 'drewry' as a member, and it can
+# even return all responses in object form just like belongs_to methods.
+# 
+#   irb> develop = Group.new('develop')
+#   => ...
+#   irb> develop.members
+#   => ["drewry", "builder"]
+#   irb> develop.members(true)
+#   => [#<User:0x000001 ...>, #<User:...>]
+# 
+# 
+# The arguments for has_many follow the exact same idea that belongs_to's
+# arguments followed. :local_key's contents are used to search for matching
+# :foreign_key content.  If :foreign_key is not specified, it defaults to the
+# dnattr of the specified :class_name.
+# 
+# === Using these new classes
+# 
+# These new classes have many method calls. Many of them are automatically
+# generated to provide access to the LDAP object's attributes. Other were defined
+# during class creation by special methods like belongs_to. There are a few other
+# methods that do not fall in to these categories.
+# 
+# 
+# ==== .find and .find_all
+# 
+# .find is a class method that is accessible from any subclass of Base that has
+# 'ldap_mapping' called. When called it returns the first match of the given
+# class.
+# 
+#   irb> Group.find('*')
+#   => "root"
+# 
+# In this simple example, Group.find took the search string of 'deve*' and
+# searched for the first match in Group where the dnattr matched the query. This
+# is the simplest example of .find.
+# 
+#   irb> Group.find_all('*')
+#   => ["root", "daemon", "bin", "sys", "adm", "tty", ..., "develop"]
+# 
+# Here .find_all returns all matches to the same query.  Both .find and .find_all
+# also can take more expressive arguments:
+# 
+#   irb> Group.find_all(:attribute => 'gidNumber', :value => '1003', :objects => false)
+#   => ["develop"]
+# 
+# So it is pretty clear what :attribute and :value do - they are used to query as
+# :attribute=:value. :objects is used to return precreated objects of the given
+# Class when it is set to true.
+# 
+#   irb> Group.find_all(:attribute => 'gidNumber', :value => '1003', :objects => false)
+#   => [#<Group:0x40674a70 ..>]
+# 
+# If :objects is unspecified, it defaults to false. If :attribute is unspecified,
+# it defaults to the dnattr.
+#
+# ==== .search
+# .search is a class method that is accessible from any subclass of Base, and Base.
+# It lets the user perform an arbitrary search against the current LDAP connection
+# irrespetive of LDAP mapping data.  This is meant to be useful as a utility method
+# to cover 80% of the cases where a user would want to use Base.connection directly.
+#
+#   irb> Base.search(:base => 'dc=example,dc=com', :filter => '(uid=roo*)',
+#                    :scope => LDAP::LDAP_SCOPE_SUBTREE, :attrs => ['uid', 'cn'])
+#   =>  [{"dn"=>"uid=root,ou=People,dc=example,dc=com","cn"=>["root"], "uidNumber"=>["0"]}]
+# You can specify the :filter, :base, :scope, and :attrs, but they all have defaults --
+#  * :filter defaults to objectClass=* - usually this isn't what you want
+#  * :base defaults to the base of the class this is executed from (as set in ldap_mapping)
+#  * :scope defaults to LDAP::LDAP_SCOPE_SUBTREE. Usually you won't need to change it
+#  * :attrs defaults to [] and is the list of attrs you want back. Empty means all of them.
+# 
+# ==== #validate
+# 
+# validate is a method that verifies that all attributes that are required by the
+# objects current objectClasses are populated. This is called by #write prior to
+# performing any action. Its explicit use in an application is unnecessary, and
+# it may become a private method in the future.
+# 
+# ==== #write
+# 
+# write is a method that writes any changes to an object back to the LDAP server.
+# It automatically handles the addition of new objects, and the modification of
+# existing ones.
+# 
+# ==== #exists?
+# 
+# exists? is a simple method which returns true is the current object exists in
+# LDAP, or false if it does not.
+# 
+#  irb> newuser = User.new("dshadsadsa")
+#  => ...
+#  irb> newuser.exists?
+#  => false
+# 
+# 
+# === ActiveLDAP::Base
+# 
+# ActiveLDAP::Base has come up a number of times in the examples above.  Every
+# time, it was being used as the super class for the wrapper objects. While this
+# is it's main purpose, it also handles quite a bit more in the background.
+# 
+# ==== What is it?
+# 
+# ActiveLDAP::Base is the heart of Ruby/ActiveLDAP.  It does all the schema
+# parsing for validation and attribute-to-method mangling as well as manage the
+# connection to LDAP.
+# 
+# ===== connect
+# 
+# Base.connect takes many (optional) arguments and is used to connect to the LDAP
+# server. Sometimes you will want to connect anonymously and other times over TLS
+# with user credentials. Base.connect is here to do all of that for you.
+# 
+# 
+# By default, if you call any subclass of Base, such as Group, it will call 
+# Base.connect() if these is no active LDAP connection. If your server allows
+# anonymous binding, and you only want to access data in a read-only fashion, you
+# won't need to call Base.connect. Here is a fully parameterized call:
+# 
+#   Base.connect(
+#     :host => 'ldap.example.com',
+#     :port => 389,
+#     :base => 'dc=example,dc=com',
+#     :bind_format => "uid=%s,ou=People,dc=example,dc=com",
+#     :logger => log4r_obj,
+#     :user => 'drewry',
+#     :password_block => Proc.new { 'password12345' },
+#     :allow_anonymous => false,
+#     :try_sasl => false
+#   )
+# 
+# There are quite a few arguments, but luckily many of them have safe defaults:
+# * :host defaults to @@host from configuration.rb waaay back at the setup.rb stage.@
+# * :port defaults to @@port from configuration.rb as well
+# * :base defaults to Base.base() from configuration.rb
+# * :bind_format defaults @@bind_format from configuration.rb
+# * :logger defaults to a Log4r object that prints fatal messages to stderr
+# * :user defaults to ENV['user']
+# * :password_block defaults to nil
+# * :allow_anonymous defaults to true
+# * :try_sasl defaults to false - see Advanced Topics for more on this one.
+# 
+# 
+# Most of these are obvious, but I'll step through them for completeness:
+# * :host defines the LDAP server hostname to connect to.
+# * :port defines the LDAP server port to connect to.
+# * :base specifies the LDAP search base to use with the prefixes defined in all
+#   subclasses.
+# * :bind_format specifies what your server expects when attempting to bind with
+#   credentials.
+# * :logger accepts a custom log4r object to integrate with any other logging
+#   your application uses.
+# * :user gives the username to substitute into bind_format for binding with
+#   credentials
+# * :password_block, if defined, give the Proc block for acquiring the password
+# * :allow_anonymous determines whether anonymous binding is allowed if other
+#   bind methods fail
+# 
+# Base.connect both connects and binds in one step. It follows roughly the following approach:
+# 
+# * Connect to host:port.
+# * Try TLS.
+# * If that fails try SSL.
+# * If that fails try no encryption.
+# 
+# * If user and password_block, attempt to bind with credentials.
+# * If that fails or no password_block and anonymous allowed, attempt to bind
+#   anonymously.
+# * If that fails, error out.
+#
+# On connect, the configuration options passed in are stored in an internal class variable
+# @@config which is used to cache the information without ditching the defaults passed in
+# from configuration.rb
+# 
+# ===== close
+# 
+# Base.close discards the current LDAP connection.
+# 
+# ===== connection
+# 
+# Base.connection returns the raw LDAP connection object.
+# 
+# === Exceptions
+# 
+# There are a few custom exceptions used in Ruby/ActiveLDAP. They are detailed below.
+# 
+# ==== AttributeEmpty
+# 
+# This exception is raised when a required attribute is empty. It is only raised
+# by #validate, and by proxy, #write.
+# 
+# ==== DeleteError
+# 
+# This exception is raised when #delete fails. It will include LDAP error
+# information that was passed up during the error.
+# 
+# ==== WriteError
+# 
+# This exception is raised when there is a problem in #write updating or creating
+# an LDAP entry.  Often the error messages are cryptic. Looking at the server
+# logs or doing an Ethereal[http://www.ethereal.com] dump of the connection will
+# often provide better insight.
+# 
+# ==== AuthenticationError
+# 
+# This exception is raised during Base.connect if no valid authentication methods
+# succeeded.
+# 
+# ==== ConnectionError
+# 
+# This exception is raised during Base.connect if no valid connection to the
+# LDAP server could be created. Check you configuration.rb, Base.connect
+# arguments, and network connectivity! Also check your LDAP server logs to see
+# if it ever saw the request.
+# 
+# === Others
+# 
+# Other exceptions may be raised by the Ruby/LDAP module, or by other subsystems.
+# If you get one of these exceptions and thing it should be wrapped, write me an
+# email and let me know where it is and what you expected. For faster results,
+# email a patch!
+# 
+# === Putting it all together
+# 
+# Now that all of the components of Ruby/ActiveLDAP have been covered, it's time
+# to put it all together! The rest of this section will show the steps to setup
+# example user and group management scripts for use with the LDAP tree described
+# above.
+# 
+# All of the scripts here are in the package's examples/ directory.
+# 
+# ==== Setting up lib/
+# 
+# In ldapadmin/lib/ create the file user.rb:
+#   cat <<EOF
+#   class User < ActiveLDAP::Base
+#     ldap_mapping :dnattr => 'uid', :prefix => 'ou=People', :classes => ['top', 'account', 'posixAccount']
+#     belongs_to :groups, :class_name => 'Group', :foreign_key => 'memberUid'
+#   end
+#   EOF
+# 
+# In ldapadmin/lib/ create the file group.rb:
+#   cat <<EOF
+#   class Group < ActiveLDAP::Base
+#     ldap_mapping :classes => ['top', 'posixGroup'], :prefix => 'ou=Group'
+#     has_many :members, :class_name => "User", :local_key => "memberUid"
+#     belongs_to :primary_members, :class_name => 'User', :foreign_key => 'gidNumber', :local_key => 'gidNumber'
+#   end # Group
+#   EOF
+# 
+# Now, we can write some small scripts to do simple management tasks.
+# 
+# ==== Creating LDAP entries
+# 
+# Now let's create a really dumb script for adding users - ldapadmin/useradd:
+# 
+#   #!/usr/bin/ruby -W0
+# 
+#   require 'activeldap'
+#   require 'lib/user'
+#   require 'lib/group'
+#   require 'password'
+# 
+#   (printf($stderr, "Usage:\n%s name cn uid\n", $0); exit 1) if ARGV.size != 3
+# 
+#   puts "Adding user #{ARGV[0]}"
+#   pwb = Proc.new {
+#     Password.get('Password: ')
+#   }
+#   ActiveLDAP::Base.connect(:password_block => pwb, :allow_anonymous => false)
+#   user = User.new(ARGV[0])
+#   user.objectClass = user.objectClass  << 'posixAccount' << 'shadowAccount'
+#   user.cn = ARGV[1]
+#   user.uidNumber = ARGV[2]
+#   user.gidNumber = ARGV[2]
+#   user.homeDirectory = "/home/#{ARGV[0]}"
+#   user.write
+#   puts "User created!"
+#   exit 0
+# 
+# 
+# ==== Managing LDAP entries
+# 
+# Now let's create another dumb script for modifying users - ldapadmin/usermod:
+# 
+#   #!/usr/bin/ruby -W0
+# 
+#   require 'activeldap'
+#   require 'lib/user'
+#   require 'lib/group'
+#   require 'password'
+# 
+#   (printf($stderr, "Usage:\n%s name cn uid\n", $0); exit 1) if ARGV.size != 3
+# 
+#   puts "Changing user #{ARGV[0]}"
+#   pwb = Proc.new {
+#     Password.get('Password: ')
+#   }
+#   ActiveLDAP::Base.connect(:password_block => pwb, :allow_anonymous => false)
+#   user = User.new(ARGV[0])
+#   user.cn = ARGV[1]
+#   user.uidNumber = ARGV[2]
+#   user.gidNumber = ARGV[2]
+#   user.write
+#   puts "Modification successful!"
+#   exit 0
+# 
+# 
+# 
+# ==== Removing LDAP entries
+# 
+# And finally, a dumb script for removing user - ldapadmin/userdel:
+# 
+# 
+#   #!/usr/bin/ruby -W0
+# 
+#   require 'activeldap'
+#   require 'lib/user'
+#   require 'lib/group'
+#   require 'password'
+# 
+#   (printf($stderr, "Usage:\n%s name\n", $0); exit 1) if ARGV.size != 1
+# 
+#   puts "Changing user #{ARGV[0]}"
+#   pwb = Proc.new {
+#     Password.get('Password: ')
+#   }
+#   ActiveLDAP::Base.connect(:password_block => pwb, :allow_anonymous => false)
+#   user = User.new(ARGV[0])
+#   user.delete
+#   puts "User has been delete"
+#   exit 0
+# 
+# === Advanced Topics
+# 
+# Below are some situation tips and tricks to get the most out of Ruby/ActiveLDAP.
+# 
+#
+# ==== Binary data and other subtypes
+#
+# Sometimes, you may want to store attributes with language specifiers, or
+# perhaps in binary form.  This is (finally!) fully supported.  To do so,
+# follow the examples below:
+#
+#   irb> user = User.new('drewry')
+#   => ...
+#   # This adds a cn entry in lang-en and whatever the server default is.
+#   irb> user.cn = [ 'wad', {'lang-en' => ['wad', 'foo']} ]
+#   => ...
+#   irb> user.cn
+#   => ["wad", {"lang-en-us" => ["wad", "Will Drewry"]}]
+#   # Now let's add a binary X.509 certificate (assume objectClass is correct)
+#   irb> user.userCertificate = File.read('example.der')
+#   => ...
+#   irb> user.write
+#
+# So that's a lot to take in. Here's what is going on. I just set the LDAP 
+# object's cn to "wad" and cn:lang-en-us to ["wad", "Will Drewry"].
+# Anytime a LDAP subtype is required, you must encapsulate the data in a Hash.
+#
+# But wait a minute, I just read in a binary certificate without wrapping it up.
+# So any binary attribute will automagically get wrapped in {'binary' => value}
+# if you don't do it. This keeps your #writes from breaking, and my code from
+# crying.  For correctness, I could have easily done the following:
+#
+#   irb>  user.userCertificate = {'binary' => File.read('example.der')}
+#
+# Really, it's up to you. The only subtypes defined in LDAPv3 are lang-* and
+# binary.  These can be nested through:
+#
+#  irb> user.cn = [{'lang-JP-jp' => {'binary' => 'somejp'}}]
+# 
+# As I understand it, OpenLDAP does not support nested subtypes, but some
+# documentation I've read suggests that Netscape's LDAP server does. I only
+# have access to OpenLDAP. If anyone tests thisout, please let me know how it 
+# goes!.
+#
+#
+# And that pretty much wraps up this section.
+#
+# ==== Further integration with your environment aka namespacing
+# 
+# If you want this to cleanly integrate into your system-wide Ruby include path,
+# you should put your extension classes inside a custom module.
+# 
+# 
+# Example:
+# 
+#   ./myldap.rb:
+#   require 'activeldap'
+#   require 'myldap/user'
+#   require 'myldap/group'
+#   module MyLDAP
+#   end
+# 
+#   ./myldap/user.rb:
+#   module MyLDAP
+#   class User < ActiveLDAP::Base
+#     ldap_mapping :dnattr => 'uid', :prefix => 'ou=People', :classes => ['top', 'account', 'posixAccount']
+#     belongs_to :groups, :class_name => 'MyLDAP::Group', :foreign_key => 'memberUid'
+#   end
+#   end
+# 
+#   ./myldap/group.rb:
+#   module MyLDAP
+#   class Group < ActiveLDAP::Base
+#     ldap_mapping :classes => ['top', 'posixGroup'], :prefix => 'ou=Group'
+#     has_many :members, :class_name => 'MyLDAP::User', :local_key => 'memberUid'
+#     belongs_to :primary_members, :class_name => 'MyLDAP::User', :foreign_key => 'gidNumber', :local_key => 'gidNumber'
+#   end
+#   end
+# 
+# Now in your local applications, you can call
+# 
+#   require 'myldap'
+# 
+#   MyLDAP::Group.new('foo')
+#   ...
+# 
+# and everything should work well.
+# 
+#
+# ==== Array results for everything
+#
+# Even though Ruby/ActiveLDAP tries to be convenient by returning Arrays only
+# when an LDAP object attribute has multiple values, sometimes this can be a
+# programmatic nightmare. If you would like to force all returned values to
+# come in Array form, just query like so:
+#
+#   irb> user = User.new('drewry')
+#   => ...
+#   irb> user.cn(true)
+#   => ["Will Drewry"]
+#
+# That's it. Now you can ALWAYS get Arrays back without having to write your own
+# wrappers.
+# 
+# ==== Dynamic attribute crawling
+# 
+# If you use tab completion in irb, you'll notice that you can't tab complete the
+# dynamic attributes available for each object. You can still see what's available with the method call
+# #attributes.
+# 
+#   irb> d = Group.new('develop')
+#   => ...
+#   irb> d.attributes
+#   => ["gidNumber", "cn", "memberUid", "commonName", "description", "userPassword", "objectClass"]
+# 
+# 
+# ==== Advanced LDAP queries
+# 
+# With the addition of Base.search, you can do arbitrary queries against LDAP
+# without needed to understand how to use Ruby/LDAP.
+#
+# If that's still not enough, you can access the
+# Ruby/LDAP connection object using the class method Base.connection.  You can
+# do all of your LDAP specific calls here and then continue about your normal
+# Ruby/ActiveLDAP business afterward.
+#
+# 
+# ==== Juggling multiple LDAP connections
+# 
+# In the same vein as the last tip, you can use multiple LDAP connections by
+# saving old connections and then resetting them as follows:
+# 
+#   irb> Base.connect()
+#   => ...
+#   irb> anon_conn = Base.connection
+#   => ...
+#   irb> Base.connect(password_block => {'mypass'})
+#   => ...
+#   irb> auth_conn = Base.connection
+#   => ...
+#   irb> Base.connection = anon_conn
+#   ...
+# 
+# This can be useful for doing authentication tests and other such tricks.
+# 
+# ==== :try_sasl
+#
+# If you have the Ruby/LDAP package with the SASL/GSSAPI patch from Ian
+# MacDonald's web site, you can use Kerberos to bind to your LDAP server. By
+# default, :try_sasl is false.
+#
+# Also note that you must be using OpenLDAP 2.1.29 or higher to use SASL/GSSAPI
+# due to some bugs in older versions of OpenLDAP.
+#
+# ==== Don't be afraid! [Internals]
+#
+# Don't be afraid to add more methods to the extensions classes and to
+# experiment. That's exactly how I ended up with this package. If you come up
+# with something cool, please share it!
+#
+# The internal structure of ActiveLDAP::Base, and thus all its subclasses, is
+# still in flux. I've tried to minimize the changes to the overall API, but
+# the internals are still rough around the edges.
+#
+# ===== Where's ldap_mapping data stored? How can I get to it?
+#
+# When you call ldap_mapping, it overwrites several class methods inherited
+# from Base:
+#   * Base.base()
+#   * Base.required_classes()
+#   * Base.dnattr()
+# You can access these from custom class methods by calling MyClass.base(),
+# or whatever. There are predefined instance methods for getting to these
+# from any new instance methods you define:
+#  * Base#base()
+#  * Base#required_classes()
+#  * Base#dnattr()
+#
+# ===== What else?
+#
+# Well if you want to use the LDAP connection for anything, I'd suggest still
+# calling Base.connection to get it. There really aren't many other internals
+# that need to be worried about.  You could rebind with Base.do_bind, and get
+# the LDAP schema with Base.schema.
+#
+# The only other useful tricks are dereferencing and accessing the stored
+# data. Since LDAP attributes can have multiple names, e.g. cn or commonName,
+# any methods you write might need to figure it out. I'd suggest just
+# calling self.[attribname] to get the value, but if that's not good enough,
+# you can call look up the stored name in the @attr_method Array as follows:
+#    irb> @attr_method['commonName']
+#    => 'cn'
+#
+# This tells you the name the attribute is stored in behind the scenes (@data).
+# Again, self.[attribname] should be enough for most extensions, but if not,
+# it's probably safe to dabble here.
+#
+# Also, if you like to look up all aliases for an attribute, you can call the
+# following:
+#
+#  irb> attribute_aliases('cn')
+#  => ['cn','commonName']
+#
+# This is discovered automagically from the LDAP server's schema.
+#
+# == Limitations
+#
+# === Speed
+# 
+# Currently, Ruby/ActiveLDAP could be faster.  I have some recursive type
+# checking going on which slows object creation down, and I'm sure there
+# are many, many other places optimizations can be done.  Feel free
+# to send patches, or just hang in there until I can optimize away the
+# slowness.
+#
+# == Feedback
+#
+# Any and all feedback and patches are welcome. I am very excited about this
+# package, and I'd like to see it prove helpful to more people than just myself.
+#
+
+
+
+require 'activeldap/base'
+require 'activeldap/associations'
+require 'activeldap/configuration'
+require 'activeldap/schema2'
+
+module ActiveLDAP
+  VERSION = "0.4.1"
+end
+
+ActiveLDAP::Base.class_eval do
+  include ActiveLDAP::Configuration
+  include ActiveLDAP::Associations
+end