treequel Manual — Connecting to a Directory

Connecting to a Directory

Once those things are done, you can fire Treequel up via IRb and get a Treequel::Directory object to play around with:

$ irb -rtreequel -rubygems
irb> dir = Treequel.directory
# => #<Treequel::Directory:0x69cbac localhost:389 (not connected) base="dc=acme,dc=com", bound as=anonymous, schema=(schema not loaded)>

Fetching a directory.

The .directory method has some reasonable defaults, so if your directory is running on localhost, you want to connect using TLS on the default port, and bind anonymously, this will be all you need.

For anything other than testing, though, it’s likely you’ll want to control the connection parameters a bit more than that. There are two options for doing this: via an LDAP URL, or with a Hash of options.

Connecting With an LDAP URL

The LDAP URL format can contain quite a lot of information, but Treequel::Directory only uses the scheme, host, port, and base DN parts:

irb> dir = Treequel.directory( 'ldap://ldap.andrew.cmu.edu/dc=cmu,dc=edu' )
# => #<Treequel::Directory:0x4f052e ldap.andrew.cmu.edu:389 (not connected) base="dc=cmu,dc=edu", bound as=anonymous, schema=(schema not loaded)>

Fetching a directory by URL.

You may omit the base DN in the URL if your environment only has one top level base (or you don’t know it!) Treequel will use the first base DN it finds from the server’s advertised namingContexts by default.

It will also use the user and password from a user:pass@host-style URL, if present, and use them to immediately bind to the directory. See the section on binding for details.

Connecting With an Options Hash

Creating a directory with an options hash allows more fine-grained control over the connection and binding parameters. It’s the same as the hash supported by Treequel::Directory’s constructor:

:host: The LDAP host to connect to.
:port: The port to connect to.
:connect_type: The type of connection to establish. Must be one of :plain, :tls, or :ssl.
:base_dn: The base DN of the directory.
:bind_dn: The DN of the user to bind as.
:pass: The password to use when binding.

Any values which you don’t provide will default to the values in Treequel::Directory::DEFAULT_OPTIONS.

irb> dir = Treequel.directory( :host => 'localhost', :base_dn => 'dc=acme,dc=com' )
# => => #<Treequel::Directory:0x4f2586 localhost:389 (not connected) base="dc=acme,dc=com",    bound as=anonymous, schema=(schema not loaded)>

Fetching a directory with an options hash.

Connecting with a URL and an Options Hash

You can also mix the two connection styles, allowing you to still use a compact URL, but set the connection_type explicitly, e.g.:

irb> dir = Treequel.directory( 'ldap://localhost/dc=acme,dc=com', :connect_type => :plain )
# => #<Treequel::Directory:0x4a0844 localhost:389 (not connected) base="dc=acme,dc=com",    bound as=anonymous, schema=(schema not loaded)>

Using both a URL and options.

Connecting With System Settings

Very often, the host you’re running on will already be using LDAP for something else, so it might not make sense to configure the connection again when you’ve already got all the information you need in the system settings.

Treequel supports using LDAP system settings to create new Treequel::Directory objects, too, using either OpenLDAP or ‘nss_ldap’ style configurations. To do this, call Treequel.directory_from_config with the path to the config file you want to load:

irb> Treequel.directory_from_config( '/usr/local/etc/openldap/ldap.conf' )
# => #<Treequel::Directory:0x4078db0c ldap.acme.com:389 (not connected) base_dn="dc=acme,dc=com", bound as=anonymous, schema=(schema not loaded)>

Load an OpenLDAP config file.

Or, just omit the argument and Treequel will search a bunch of common paths¹ for a config file and load the first one it finds:

irb> Treequel.log.level = Logger::INFO
# => 1
irb> Treequel.directory_from_config
[2010-08-20 17:04:40.648875 41003/main]  INFO -- Searching common paths for ldap.conf
[2010-08-20 17:04:40.650592 41003/main]  INFO -- Reading config options from /etc/openldap/ldap.conf...
# => #<Treequel::Directory:0x4078db0c ldap.acme.com:389 (not connected) base_dn="dc=acme,dc=com", bound as=anonymous, schema=(schema not loaded)>

Load the config from a common path.

It also supports overriding elements of the LDAP configuration via OpenLDAP-style environment variables, too:

irb> ENV['LDAPHOST'] = 'ldap-master.acme.com'
# => "ldap-master.acme.com"
irb> Treequel.directory_from_config( '/etc/openldap/ldap.conf' )
[2010-08-20 17:19:57.686113 41432/main]  INFO -- Reading config options from /etc/openldap/ldap.conf...
# => #<Treequel::Directory:0x4078c266 ldap-master.acme.com:389 (not connected) base_dn="dc=acme,dc=com", bound as=anonymous, schema=(schema not loaded)>

Override the configured host to connect to the master.

¹ If there’s one missing, let us know and we’ll add it! --