Class: Net::LDAP
- Inherits:
-
Object
- Object
- Net::LDAP
- Defined in:
- lib/net/ldap.rb,
lib/net/ldap.rb,
lib/net/ldap/psw.rb,
lib/net/ldap/entry.rb,
lib/net/ldap/filter.rb,
lib/net/ldap/dataset.rb
Overview
Net::LDAP
This library provides a pure-Ruby implementation of the LDAP client protocol, per RFC-1777. 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 the LDAP protocol itself, and thus presenting as Ruby-like a programming interface as possible.
Quick-start for the Impatient
require 'rubygems'
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
Quick introduction to LDAP
We’re going to provide a quick and highly informal introduction to LDAP terminology and typical operations. If you’re comfortable with this material, skip ahead to “How to use Net::LDAP.” If you want a more rigorous treatment of this material, we recommend you start with the various IETF and ITU standards that control LDAP.
Entities
LDAP is an Internet-standard protocol used to access directory servers. The basic search unit is the entity, which corresponds to a person or other domain-specific object. A directory service which supports the LDAP protocol typically stores information about a number of entities.
Principals
LDAP servers are typically used to access information about people, but also very often about such items as printers, computers, and other resources. To reflect this, LDAP uses the term entity, or less commonly, principal, to denote its basic data-storage unit.
Distinguished Names
In LDAP’s view of the world, an entity is uniquely identified by a globally-unique text string called a Distinguished Name, originally defined in the X.400 standards from which LDAP is ultimately derived. Much like a DNS hostname, a DN is a “flattened” text representation of a string of tree nodes. Also like DNS (and unlike Java package names), a DN expresses a chain of tree-nodes written from left to right in order from the most-resolved node to the most-general one.
If you know the DN of a person or other entity, then you can query an LDAP-enabled directory for information (attributes) about the entity. Alternatively, you can query the directory for a list of DNs matching a set of criteria that you supply.
Attributes
In the LDAP view of the world, a DN uniquely identifies an entity. Information about the entity is stored as a set of Attributes. An attribute is a text string which is associated with zero or more values. Most LDAP-enabled directories store a well-standardized range of attributes, and constrain their values according to standard rules.
A good example of an attribute is cn,
which stands for “Common Name.” In many directories, this attribute is used to store a string consisting of a person’s first and last names. Most directories enforce the convention that an entity’s cn
attribute have exactly one value. In LDAP jargon, that means that cn
must be present and single-valued.
Another attribute is mail,
which is used to store email addresses. (No, there is no attribute called “email,” perhaps because X.400 terminology predates the invention of the term email.) mail
differs from cn
in that most directories permit any number of values for the mail
attribute, including zero.
Tree-Base
We said above that X.400 Distinguished Names are globally unique. In a manner reminiscent of DNS, LDAP supposes that each directory server contains authoritative attribute data for a set of DNs corresponding to a specific sub-tree of the (notional) global directory tree. This subtree is generally configured into a directory server when it is created. It matters for this discussion because most servers will not allow you to query them unless you specify a correct tree-base.
Let’s say you work for the engineering department of Big Company, Inc., whose internet domain is bigcompany.com. You may find that your departmental directory is stored in a server with a defined tree-base of
ou=engineering,dc=bigcompany,dc=com
You will need to supply this string as the tree-base when querying this directory. (Ou is a very old X.400 term meaning “organizational unit.” Dc is a more recent term meaning “domain component.”)
LDAP Versions
(stub, discuss v2 and v3)
LDAP Operations
The essential operations are: #bind, #search, #add, #modify, #delete, and #rename.
Bind
#bind supplies a user’s authentication credentials to a server, which in turn verifies or rejects them. There is a range of possibilities for credentials, but most directories support a simple username and password authentication.
Taken by itself, #bind can be used to authenticate a user against information stored in a directory, for example to permit or deny access to some other resource. In terms of the other LDAP operations, most directories require a successful #bind to be performed before the other operations will be permitted. Some servers permit certain operations to be performed with an “anonymous” binding, meaning that no credentials are presented by the user. (We’re glossing over a lot of platform-specific detail here.)
Search
Calling #search against the directory involves specifying a treebase, a set of search filters, and a list of attribute values. The filters specify ranges of possible values for particular attributes. Multiple filters can be joined together with AND, OR, and NOT operators. A server will respond to a #search by returning a list of matching DNs together with a set of attribute values for each entity, depending on what attributes the search requested.
Add
#add operation specifies a new DN and an initial set of attribute values. If the operation succeeds, a new entity with the corresponding DN and attributes is added to the directory.
Modify
#modify specifies an entity DN, and a list of attribute operations. #modify is used to change the attribute values stored in the directory for a particular entity. #modify may add or delete attributes (which are lists of values) or it change attributes by adding to or deleting from their values. There are three easier methods to modify an entry’s attribute values: #add_attribute, #replace_attribute, and #delete_attribute.
Delete
#delete operation specifies an entity DN. If it succeeds, the entity and all its attributes is removed from the directory.
Rename (or Modify RDN)
#rename (or #modify_rdn) is an operation added to version 3 of the LDAP protocol. It responds to the often-arising need to change the DN of an entity without discarding its attribute values. In earlier LDAP versions, the only way to do this was to delete the whole entity and add it again with a different DN.
#rename works by taking an “old” DN (the one to change) and a “new RDN,” which is the left-most part of the DN string. If successful, #rename changes the entity DN so that its left-most node corresponds to the new RDN given in the request. (RDN, or “relative distinguished name,” denotes a single tree-node as expressed in a DN, which is a chain of tree nodes.)
How to use Net::LDAP
To access Net::LDAP functionality in your Ruby programs, start by requiring the library:
require 'net/ldap'
If you installed the Gem version of Net::LDAP, and depending on your version of Ruby and rubygems, you may also need to require rubygems explicitly:
require 'rubygems'
require 'net/ldap'
Most operations with Net::LDAP start by instantiating a Net::LDAP object. The constructor for this object takes arguments specifying the network location (address and port) of the LDAP server, and also the binding (authentication) credentials, typically a username and password. Given an object of class Net:LDAP, you can then perform LDAP operations by calling instance methods on the object. These are documented with usage examples below.
The Net::LDAP library is designed to be very disciplined about how it makes network connections to servers. This is different from many of the standard native-code libraries that are provided on most platforms, which share bloodlines with the original Netscape/Michigan LDAP client implementations. These libraries sought to insulate user code from the workings of the network. This is a good idea of course, but the practical effect has been confusing and many difficult bugs have been caused by the opacity of the native libraries, and their variable behavior across platforms.
In general, Net::LDAP instance methods which invoke server operations make a connection to the server when the method is called. They execute the operation (typically binding first) and then disconnect from the server. The exception is Net::LDAP#open, which makes a connection to the server and then keeps it open while it executes a user-supplied block. Net::LDAP#open closes the connection on completion of the block.
Defined Under Namespace
Classes: Connection, Dataset, Entry, Filter, LdapError, Password
Constant Summary collapse
- VERSION =
"0.0.1"
- SearchScope_BaseObject =
0
- SearchScope_SingleLevel =
1
- SearchScope_WholeSubtree =
2
- SearchScopes =
[SearchScope_BaseObject, SearchScope_SingleLevel, SearchScope_WholeSubtree]
- AsnSyntax =
{ :application => { :constructed => { 0 => :array, # BindRequest 1 => :array, # BindResponse 2 => :array, # UnbindRequest 3 => :array, # SearchRequest 4 => :array, # SearchData 5 => :array, # SearchResult 6 => :array, # ModifyRequest 7 => :array, # ModifyResponse 8 => :array, # AddRequest 9 => :array, # AddResponse 10 => :array, # DelRequest 11 => :array, # DelResponse 12 => :array, # ModifyRdnRequest 13 => :array, # ModifyRdnResponse 14 => :array, # CompareRequest 15 => :array, # CompareResponse 16 => :array, # AbandonRequest 24 => :array, # Unsolicited Notification } }, :context_specific => { :primitive => { 0 => :string, # password 1 => :string, # Kerberos v4 2 => :string, # Kerberos v5 } } }
- DefaultHost =
"127.0.0.1"
- DefaultPort =
389
- DefaultAuth =
{:method => :anonymous}
- ResultStrings =
{ 0 => "Success", 1 => "Operations Error", 2 => "Protocol Error", 16 => "No Such Attribute", 17 => "Undefined Attribute Type", 20 => "Attribute or Value Exists", 32 => "No Such Object", 34 => "Invalid DN Syntax", 48 => "Invalid DN Syntax", 48 => "Inappropriate Authentication", 49 => "Invalid Credentials", 50 => "Insufficient Access Rights", 51 => "Busy", 52 => "Unavailable", 53 => "Unwilling to perform", 65 => "Object Class Violation", 68 => "Entry Already Exists" }
Class Method Summary collapse
-
.open(args) ⇒ Object
#open takes the same parameters as #new.
-
.result2string(code) ⇒ Object
LDAP::result2string.
Instance Method Summary collapse
-
#add(args) ⇒ Object
Adds a new entry to the remote LDAP server.
-
#add_attribute(dn, attribute, value) ⇒ Object
Add a value to an attribute.
-
#bind ⇒ Object
#bind connects to the LDAP server and requests authentication based on the
:auth
parameter passed to #open or #new. -
#bind_as ⇒ Object
#bind_as is for testing authentication credentials.
-
#delete(args) ⇒ Object
Delete an entry from the LDAP directory.
-
#delete_attribute(dn, attribute) ⇒ Object
Delete an attribute and all its values.
-
#get_operation_result ⇒ Object
Returns a meaningful result any time after a protocol operation (#bind, #search, #add, #modify, #rename, #delete) has completed.
-
#initialize(args = {}) ⇒ LDAP
constructor
Instantiate an object of type Net::LDAP to perform directory operations.
-
#modify(args) ⇒ Object
DEPRECATED - Please use #add_attribute, #replace_attribute, or #delete_attribute.
-
#modify_rdn(args) ⇒ Object
modify_rdn is an alias for #rename.
-
#open {|_self| ... } ⇒ Object
Opens a network connection to the server and then passes
self
to the caller-supplied block. -
#rename(args) ⇒ Object
Rename an entry on the remote DIS by changing the last RDN of its DN.
-
#replace_attribute(dn, attribute, value) ⇒ Object
Replace the value of an attribute.
-
#search(args) ⇒ Object
Searches the LDAP directory for directory entries.
-
#searchx(args) ⇒ Object
DEPRECATED. Performs an LDAP search, waits for the operation to complete, and passes a result set to the caller-supplied block.
Constructor Details
#initialize(args = {}) ⇒ LDAP
Instantiate an object of type Net::LDAP to perform directory operations. This constructor takes a Hash containing arguments. The following arguments are supported:
-
:host => the LDAP server’s IP-address (default 127.0.0.1)
-
:port => the LDAP server’s TCP port (default 389)
-
:auth => a Hash containing authorization parameters. Currently supported values include: => :anonymous and {:method => :simple, :username => your_user_name, :password => your_password }
Instantiating a Net::LDAP object does not result in network traffic to the LDAP server. It simply stores the connection and binding parameters in the object.
326 327 328 329 330 331 332 333 334 335 336 |
# File 'lib/net/ldap.rb', line 326 def initialize args = {} @host = args[:host] || DefaultHost @port = args[:port] || DefaultPort @verbose = false # Make this configurable with a switch on the class. @auth = args[:auth] || DefaultAuth # This variable is only set when we are created with LDAP::open. # All of our internal methods will connect using it, or else # they will create their own. @open_connection = nil end |
Class Method Details
.open(args) ⇒ Object
#open takes the same parameters as #new. #open makes a network connection to the LDAP server and then passes a newly-created Net::LDAP object to the caller-supplied block. Within the block, you can call any of the instance methods of Net::LDAP to perform operations against the LDAP directory. #open will perform all the operations in the user-supplied block on the same network connection, which will be closed automatically when the block finishes.
# (PSEUDOCODE)
auth = {:method => :simple, :username => username, :password => password}
Net::LDAP.open( :host => ipaddress, :port => 389, :auth => auth ) do |ldap|
ldap.search( ... )
ldap.add( ... )
ldap.modify( ... )
end
353 354 355 356 |
# File 'lib/net/ldap.rb', line 353 def LDAP::open args ldap1 = LDAP.new args ldap1.open {|ldap| yield ldap } end |
.result2string(code) ⇒ Object
LDAP::result2string
309 310 311 |
# File 'lib/net/ldap.rb', line 309 def LDAP::result2string code ResultStrings[code] || "unknown result (#{code})" end |
Instance Method Details
#add(args) ⇒ Object
Adds a new entry to the remote LDAP server. Supported arguments:
- :dn
-
Full DN of the new entry
- :attributes
-
Attributes of the new entry.
The attributes argument is supplied as a Hash keyed by Strings or Symbols giving the attribute name, and mapping to Strings or Arrays of Strings giving the actual attribute values. Observe that most LDAP directories enforce schema constraints on the attributes contained in entries. #add will fail with a server-generated error if your attributes violate the server-specific constraints. Here’s an example:
dn = "cn=George Smith,ou=people,dc=example,dc=com"
attr = {
:cn => "George Smith",
:objectclass => ["top", "inetorgperson"],
:sn => "Smith",
:mail => "[email protected]"
}
Net::LDAP.open (:host => host) do |ldap|
ldap.add( :dn => dn, :attributes => attr )
end
590 591 592 593 594 595 596 597 598 599 600 601 602 |
# File 'lib/net/ldap.rb', line 590 def add args if @open_connection @result = @open_connection.add( args ) else @result = 0 conn = Connection.new( :host => @host, :port => @port ) if (@result = conn.bind( args[:auth] || @auth )) == 0 @result = conn.add( args ) end conn.close end @result == 0 end |
#add_attribute(dn, attribute, value) ⇒ Object
Add a value to an attribute. Takes the full DN of the entry to modify, the name (Symbol or String) of the attribute, and the value (String or Array). If the attribute does not exist (and there are no schema violations), #add_attribute will create it with the caller-specified values. If the attribute already exists (and there are no schema violations), the caller-specified values will be added to the values already present.
Returns True or False to indicate whether the operation succeeded or failed, with extended information available by calling #get_operation_result. See also #replace_attribute and #delete_attribute.
dn = "cn=modifyme,dc=example,dc=com"
ldap.add_attribute dn, :mail, "[email protected]"
704 705 706 |
# File 'lib/net/ldap.rb', line 704 def add_attribute dn, attribute, value modify :dn => dn, :operations => [[:add, attribute, value]] end |
#bind ⇒ Object
#bind connects to the LDAP server and requests authentication based on the :auth
parameter passed to #open or #new. It takes no parameters. User code generally will not call #bind. It will be called implicitly by the library whenever an LDAP operation is requested. #bind can be useful to test authentication. – If there is an @open_connection, then perform the bind on it. Otherwise, connect, bind, and disconnect. The latter operation is obviously useful only as an auth check.
540 541 542 543 544 545 546 547 548 549 550 |
# File 'lib/net/ldap.rb', line 540 def bind if @open_connection @result = @open_connection.bind @auth else conn = Connection.new( :host => @host, :port => @port ) @result = conn.bind @auth conn.close end @result == 0 end |
#bind_as ⇒ Object
#bind_as is for testing authentication credentials. Most likely a “standard” name (like a CN or an email address) will be presented along with a password. We’ll bind with the main credential given in the constructor, query the full DN of the user given to us as a parameter, then unbind and rebind as the new user.
This method is currently an unimplemented stub.
563 564 |
# File 'lib/net/ldap.rb', line 563 def bind_as end |
#delete(args) ⇒ Object
Delete an entry from the LDAP directory. Takes a hash of arguments. The only supported argument is :dn, which must give the complete DN of the entry to be deleted. Returns True or False to indicate whether the delete succeeded. Extended status information is available by calling #get_operation_result.
dn = "[email protected],ou=people,dc=example,dc=com"
ldap.delete :dn => dn
776 777 778 779 780 781 782 783 784 785 786 787 788 |
# File 'lib/net/ldap.rb', line 776 def delete args if @open_connection @result = @open_connection.delete( args ) else @result = 0 conn = Connection.new( :host => @host, :port => @port ) if (@result = conn.bind( args[:auth] || @auth )) == 0 @result = conn.delete( args ) end conn.close end @result == 0 end |
#delete_attribute(dn, attribute) ⇒ Object
Delete an attribute and all its values. Takes the full DN of the entry to modify, and the name (Symbol or String) of the attribute to delete.
Returns True or False to indicate whether the operation succeeded or failed, with extended information available by calling #get_operation_result. See also #add_attribute and #replace_attribute.
dn = "cn=modifyme,dc=example,dc=com"
ldap.delete_attribute dn, :mail
738 739 740 |
# File 'lib/net/ldap.rb', line 738 def delete_attribute dn, attribute modify :dn => dn, :operations => [[:delete, attribute, nil]] end |
#get_operation_result ⇒ Object
Returns a meaningful result any time after a protocol operation (#bind, #search, #add, #modify, #rename, #delete) has completed. It returns an #OpenStruct containing an LDAP result code (0 means success), and a human-readable string.
unless ldap.bind
puts "Result: #{ldap.get_operation_result.code}"
puts "Message: #{ldap.get_operation_result.}"
end
368 369 370 371 372 373 374 375 376 377 |
# File 'lib/net/ldap.rb', line 368 def get_operation_result os = OpenStruct.new if @result os.code = @result else os.code = 0 end os. = LDAP.result2string( os.code ) os end |
#modify(args) ⇒ Object
DEPRECATED - Please use #add_attribute, #replace_attribute, or #delete_attribute.
Modifies the attribute values of a particular entry on the LDAP directory. Takes a hash with arguments. Supported arguments are:
- :dn
-
(the full DN of the entry whose attributes are to be modified)
- :operations
-
(the modifications to be performed, detailed next)
This method returns True or False to indicate whether the operation succeeded or failed, with extended information available by calling #get_operation_result.
The LDAP protocol provides a full and well thought-out set of operations for changing the values of attributes, but they are necessarily somewhat complex and not always intuitive. If these instructions are confusing or incomplete, please send us email or create a bug report on rubyforge.
The :operations parameter to #modify takes an array of operation-descriptors. Each individual operation is specified in one element of the array, and most LDAP servers will attempt to perform the operations in order.
Each of the operations appearing in the Array must itself be an Array with exactly three elements:
- an operator
-
must be :add, :replace, or :delete
- an attribute name
-
the attribute name (string or symbol) to modify
- a value
-
either a string or an array of strings.
The :add operator will, unsurprisingly, add the specified values to the specified attribute. If the attribute does not already exist, :add will create it. Most LDAP servers will generate an error if you to add a value that already exists.
:replace will erase the current value(s) for the specified attribute, if there are any, and replace them with the specified value(s).
:delete will remove the specified value(s) from the specified attribute. If you pass nil, an empty string, or an empty array as the value parameter to a :delete operation, the entire attribute will be deleted.
For example:
dn = "[email protected],ou=people,dc=example,dc=com"
ops = [
[:add, :mail, "[email protected]"],
[:replace, :mail, ["[email protected]", "[email protected]"]],
[:delete, :sn, nil]
]
ldap.modify :dn => dn, :operations => ops
(This example is contrived since you probably wouldn’t add a mail value right before replacing the whole attribute, but it shows that order of execution matters. Also, many LDAP servers won’t let you delete SN because it would be a schema violation.)
It’s essential to keep in mind that if you specify more than one operation in a call to #modify, most LDAP servers will attempt to perform all of the operations in the order you gave them. This matters because you may specify operations on the same attribute which must be performed in a certain order. Most LDAP servers will stop processing your modifications if one of them causes an error on the server (such as a schema-constraint violation). If this happens, you will probably get a result code from the server that reflects only the operation that failed, and you may or may not get extended information that will tell you which one failed. #modify has no notion of an atomic transaction. If you specify a chain of modifications in one call to #modify, and one of them fails, the preceding ones will usually not be “rolled back,” resulting in a partial update. This is a limitation of the LDAP protocol, not of Net::LDAP.
674 675 676 677 678 679 680 681 682 683 684 685 686 |
# File 'lib/net/ldap.rb', line 674 def modify args if @open_connection @result = @open_connection.modify( args ) else @result = 0 conn = Connection.new( :host => @host, :port => @port ) if (@result = conn.bind( args[:auth] || @auth )) == 0 @result = conn.modify( args ) end conn.close end @result == 0 end |
#modify_rdn(args) ⇒ Object
modify_rdn is an alias for #rename.
761 762 763 |
# File 'lib/net/ldap.rb', line 761 def modify_rdn args rename args end |
#open {|_self| ... } ⇒ Object
Opens a network connection to the server and then passes self
to the caller-supplied block. The connection is closed when the block completes. Used for executing multiple LDAP operations without requiring a separate network connection (and authentication) for each one. Note: You do not need to log-in or “bind” to the server. This will be done for you automatically. For an even simpler approach, see the class method Net::LDAP#open.
# (PSEUDOCODE)
auth = {:method => :simple, :username => username, :password => password}
ldap = Net::LDAP.new( :host => ipaddress, :port => 389, :auth => auth )
ldap.open do |ldap|
ldap.search( ... )
ldap.add( ... )
ldap.modify( ... )
end
– First we make a connection and then a binding, but we don’t do anything with the bind results. We then pass self to the caller’s block, where he will execute his LDAP operations. Of course they will all generate auth failures if the bind was unsuccessful.
403 404 405 406 407 408 409 |
# File 'lib/net/ldap.rb', line 403 def open raise LdapError.new( "open already in progress" ) if @open_connection @open_connection = Connection.new( :host => @host, :port => @port ) @open_connection.bind @auth yield self @open_connection.close end |
#rename(args) ⇒ Object
Rename an entry on the remote DIS by changing the last RDN of its DN. Documentation stub
746 747 748 749 750 751 752 753 754 755 756 757 758 |
# File 'lib/net/ldap.rb', line 746 def rename args if @open_connection @result = @open_connection.rename( args ) else @result = 0 conn = Connection.new( :host => @host, :port => @port ) if (@result = conn.bind( args[:auth] || @auth )) == 0 @result = conn.rename( args ) end conn.close end @result == 0 end |
#replace_attribute(dn, attribute, value) ⇒ Object
Replace the value of an attribute. #replace_attribute can be thought of as equivalent to calling #delete_attribute followed by #add_attribute. It takes the full DN of the entry to modify, the name (Symbol or String) of the attribute, and the value (String or Array). If the attribute does not exist, it will be created with the caller-specified value(s). If the attribute does exist, its values will be discarded and replaced with the caller-specified values.
Returns True or False to indicate whether the operation succeeded or failed, with extended information available by calling #get_operation_result. See also #add_attribute and #delete_attribute.
dn = "cn=modifyme,dc=example,dc=com"
ldap.replace_attribute dn, :mail, "[email protected]"
723 724 725 |
# File 'lib/net/ldap.rb', line 723 def replace_attribute dn, attribute, value modify :dn => dn, :operations => [[:replace, attribute, value]] end |
#search(args) ⇒ Object
Searches the LDAP directory for directory entries. Takes a hash argument with parameters. Supported parameters include:
-
:base (a string specifying the tree-base for the search);
-
:filter (an object of type Net::LDAP::Filter, defaults to objectclass=*);
-
:attributes (a string or array of strings specifying the LDAP attributes to return from the server);
-
:return_result (a boolean specifying whether to return a result set).
-
:attributes_only (a boolean flag, defaults false)
-
:scope (one of: Net::LDAP::SearchScope_BaseObject, Net::LDAP::SearchScope_SingleLevel, Net::LDAP::SearchScope_WholeSubtree. Default is WholeSubtree.)
#search queries the LDAP server and passes each entry to the caller-supplied block, as an object of type Net::LDAP::Entry. If the search returns 1000 entries, the block will be called 1000 times. If the search returns no entries, the block will not be called.
#search returns either a result-set or a boolean, depending on the value of the :return_result
argument. The default behavior is to return a result set, which is a hash. Each key in the hash is a string specifying the DN of an entry. The corresponding value for each key is a Net::LDAP::Entry object. If you request a result set and #search fails with an error, it will return nil. Call #get_operation_result to get the error information returned by the LDAP server.
When :return_result => false,
#search will return only a Boolean, to indicate whether the operation succeeded. This can improve performance with very large result sets, because the library can discard each entry from memory after your block processes it.
treebase = "dc=example,dc=com"
filter = Net::LDAP::Filter.eq( "mail", "a*.com" )
attrs = ["mail", "cn", "sn", "objectclass"]
ldap.search( :base => treebase, :filter => filter, :attributes => attrs, :return_result => false ) do |entry|
puts "DN: #{entry.dn}"
entry.each do |attr, values|
puts ".......#{attr}:"
values.each do |value|
puts " #{value}"
end
end
end
– This is a re-implementation of search that replaces the original one (now renamed searchx and possibly destined to go away). The difference is that we return a dataset (or nil) from the call, and pass _each entry_ as it is received from the server to the caller-supplied block. This will probably make things far faster as we can do useful work during the network latency of the search. The downside is that we have no access to the whole set while processing the blocks, so we can’t do stuff like sort the DNs until after the call completes. It’s also possible that this interacts badly with server timeouts. We’ll have to ensure that something reasonable happens if the caller has processed half a result set when we throw a timeout error. Another important difference is that we return a result set from this method rather than a T/F indication. Since this can be very heavy-weight, we define an argument flag that the caller can set to suppress the return of a result set, if he’s planning to process every entry as it comes from the server.
506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 |
# File 'lib/net/ldap.rb', line 506 def search args result_set = (args and args[:return_result] == false) ? nil : {} if @open_connection @result = @open_connection.search( args ) {|entry| result_set[entry.dn] = entry if result_set yield( entry ) if block_given? } else @result = 0 conn = Connection.new( :host => @host, :port => @port ) if (@result = conn.bind( args[:auth] || @auth )) == 0 @result = conn.search( args ) {|entry| (result_set[entry.dn] = entry) if result_set yield( entry ) if block_given? } end conn.close end @result == 0 and result_set end |
#searchx(args) ⇒ Object
DEPRECATED. Performs an LDAP search, waits for the operation to complete, and passes a result set to the caller-supplied block. – If an open call is in progress (@open_connection will be non-nil), then ASSUME a bind has been performed and accepted, and just execute the search. If @open_connection is nil, then we have to connect, bind, search, and then disconnect. (The disconnect is not strictly necessary but it’s friendlier to the network to do it here rather than waiting for Ruby’s GC.) Note that in the standalone case, we’re permitting the caller to modify the auth parms.
425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 |
# File 'lib/net/ldap.rb', line 425 def searchx args if @open_connection @result = @open_connection.searchx( args ) {|values| yield( values ) if block_given? } else @result = 0 conn = Connection.new( :host => @host, :port => @port ) if (@result = conn.bind( args[:auth] || @auth )) == 0 @result = conn.searchx( args ) {|values| yield( values ) if block_given? } end conn.close end @result == 0 end |