PerLDA

1
PerLDAP

• LDAP for the rest of us!

Leif Hedstromltleif_at_netscape.comgt Netscape
Communications Corp.
2
Agenda

• Why PerLDAP? History of PerLDAP
• Introduction to Perl and Perl Objects
• Installing PerLDAP
• Overview of the PerLDAP architecture
• API (API.pm)
• Connections (Conn.pm)
• Entries (Entry.pm)
• Other (Util.pm, LDIF.pm, and more)

3
Agenda (cont.)

• Simple tasks (examples)
• Authentication
• Searching for entries
• Modifying entries
• Deleting an entry
• Adding an entry
• Case study modattr.pl
• Future directions, contributions etc.

4
Why PerLDAP?

• Primary Goal Easy to use!
• Why Perl? Powerful, feature rich, accepted
  standard, well known, easy to learn
• Internal need at Netscape led to first
  implementation
• C-API powerful, but too low level for simple
  tasks
• But, PerLDAP is almost 100 compatible

5
History

• Early 1997 Netscape IS needs tools for LDAP
  management
• Continued development of a Perl module named
  Ldapp
• Aug 1998 Code merge of Ldapp and Clayton
  Donleys Perl API
• Now PerLDAP v1.2.2 released, v1.4 next

6
Larry Wall on Perl5 Objects

• An object is simply a referenced thingy that
  happens to know which class it belongs to.
• A class is simply a package that happens to
  provide methods to deal with objects.
• A method is simply a subroutine that expects an
  object reference (or a package name, for class
  methods) as its first argument.

7
My comments on Perl5 Objects

• Not strictly Object Oriented
• Not real inheritance (use _at_ISA)
• Can not hide data (no private data)
• No real datatypes, typically uses hash arrays
• No difference on class and instance methods
• Methods are regular Perl functions, instance
  pointer passed as first argument
• Kludge?

8
Example Perl5 object/module

• package NetscapeTest
• sub new
• my (class, init) _at__
• my self Hash array class data
• self-gtstatus Some Value
• self-gtinit(init) Call class initializer
• ...
• Return bless self, class
• sub DESTROY
• ...
• 1

9
Example Using the new class

• !/usr/bin/perl5
• use NetscapeTest
• tester new NetscapeTest()
• tester2 new NetscapeTest( foo gt bar)
• tester-gtdoSomething(argument)
• print Status is , tester-gtstatus, \n
• delete tester

10
Installing PerLDAP

• v1.2 is available in /tools/ns (for perl5.004)
• Source from Mozilla (cvs) and DevEdge
• Requires Perl v5.004 or later (get v5.005_03 if
  possible!)
• Needs an ANSI C compiler, e.g. gcc
• C-SDK v1.0 or v3.0, on Unix and Win/NT
• Standard Perl installation, Makefile.PL

11
PerLDAP architecture

• Three layers
• C-SDK, LDAP functionality
• API.so/API.pm interfaces Perl and the SDK
• Object Oriented glue, synchronous LDAP only,
  but next version might use asynchronous calls
• You can write PerLDAP scripts that are
  similar/compatible with the plain C-API.
• Easier Use the OO layer

12
API.so and API.pm

• Implements the C-SDK functions, see PerLDAP
  Programmers Guide for details
• Can be used directly from Perl scripts, by use
  of the API.pm module
• Should be completely LDAP v2 and v3 capable, but
  many new v3 features are not well tested
• Avoid using it unless you need the low level
  features. Better, write an OO module!

13
Getting a connection Conn.pm

• Core module/object for handling a connection to
  an LDAP server
• Main methods
• new Create new LDAP connection
• search Perform an LDAP search
• searchURL Like search, but with a URL
• nextEntry Retrieve subsequent entries
• newEntry Create an empty Entry object

14
Conn.pm methods (cont.)

• delete Delete an LDAP entry
• add Add a new entry
• modifyRDN Change the RDN of an entry
• update Commit changes made to entry
• close Close the LDAP connections

15
Conn.pm methods (cont.)

• Error handling
• getErrorCode Get the last error code
• getErrorString Get the last error string
• printEror Print the last error (stdout)
• In general Returns null or False on errors
• No exception handling in Perl -(

16
Conn.pm methods (cont.)

• Other methods
• simpleAuth Perform a new bind operation
• isURL Is a string a proper LDAP URL?
• getRes Get internal result handle
• getLD Get internal LDAP handle
• setRebindProc Rebind proc
• setDefaultRebindProc simple rebind

17
Example Getting connected

• conn new MozillaLDAPConn(\ld)
• die Wow, you suck! unless conn
• conn new MozillaLDAPConn(host gt
  ldap,
• port gt 389,
• bind gt dn,
• pswd gt
  pswd)
• conn new MozillaLDAPConn(ldap,389)
• conn new MozillaLDAPConn(ldap,
  636,dn,
• pwd, certfile)

18
Connection parameters

• 1 host gt LDAP host name
• 2 port gt TCP port to connect to
• 3 bind gt DN to bind as
• 4 pswd gt Password to authenticate
• 5 cert gt Path to CertDB file
• (3 - 5 are optional, defaults to anonymous)

19
Manage your entry Entry.pm

• Returned by the Connsearch() and
  ConnnextEntry() methods
• Basically a Perl hash array (uses TieHash)
• Attribute value is a pointer to an array, except
  DN which is a single value
• You can use normal Perl functions to retrieve,
  delete and modify values
• But, plenty of class/instance methods!

20
Entry.pm methods

• Manipulating attributes
• addValue Add an attribute value
• addDNValue Add a DN value
• removeValue Remove an attribute value
• removeDNValue Remove DN value
• setValue Replace the entire attribute
• remove Delete an entire attribute
• unRemove Undo remove/removeValue

21
Entry.pm methods (cont.)

• Query methods
• isModified Has attribute been touched?
• isDeleted Has the attribute been deleted?
• isAttr Is the argument a valid attribute?
• hasValue Does the attribute have value?
• hasDNValue Like hasValue, but DN normalized
• matchValue Like hasValue, but use regexps
• matchDNValue Like matchValue, but DNs

22
Entry.pm methods (cont.)

• size Return the number of values in an attr.
• exists Legacy code, use isAttr() instead
• Other methods
• printLDIF Print entry in LDIF format
• attrModified Mark an attribute as modified
• getDN Get the entry DN
• setDN Set the entry DN (use with add)
• new Create a new, empty, entry

23
Entry.pm methods (cont.)

• TieHASH methods
• STORE Catch attribute modifications
• FETCH Catch attribute retrievals
• DELETE Catch deleting entire attributes
• EXISTS Does the attribute/key exist?
• FIRSTKEY Get the first attribute in entry
• NEXTKEY Get next attribute in entry

24
Examples Entry.pm methods

• print CN is , entry-gtcn0, \n
• print DN is , entry-gtdn, \n
• print DN is , entry-gtgetDN(), \n
• entry-gtsn Hedstrom, The Swede
• entry-gtsetDN(uidleif,dcogre,dccom)
• entry-gtsetValue(foo, (a, b, c))
• entry-gtaddValue(mail, leif_at_ogre.com)
• entry-gtremoveValue(cn, The Swede)
• entry-gtremoveDNValue(seeAlso, value)
• delete entry-gtdescription
• entry-gtdelete(description)
• if (entry-gthasValue(mail, leif_at_ogre.com,
  1))
• foreach attr (keys(entry))

25
Other modules

• Utils.pm contains lots of useful little utilities
• LDIF.pm to work with LDIF file. New version on
  the way, contributed by John Kristian (available
  as of v1.3.1)
• Lots of useful modules on CPAN, like MIMEBase64
• perl5 -MCPAN -e shell

26
Example Authentication

• !/usr/bin/perl5
• use MozillaLDAPConn
• setup global parameters, using Getopt
• srch (uid . ENVUSER . )
• c new MozillaLDAPConn(host,port)
• entry c-gtsearch(base, SUB, srch)
• if (entry !c-gtnextEntry()
• dn entry-gtgetDN()
• die Bummer dude! unless
• conn-gtsimpleAuth(dn,pwd)
• We had a good authentication, go on!
• c-gtclose() if c

27
Example Simple searches

• !/usr/bin/perl5
• use MozillaLDAPConn
• setup global parameters, using Getopt
• c new MozillaLDAPConn(\ld)
• entry c-gtsearch(base, ONE, srch)
• while (entry)
• entry-gtprintLDIF()
• entry c-gtnextEntry()
• c-gtclose() if c

28
Example Modifying entries

• !/usr/bin/perl5
• use MozillaLDAPConn
• setup global parameters, using Getopt
• c new MozillaLDAPConn(\ld)
• entry c-gtsearch(base, sc, srch)
• while (entry)
• entry-gtsetValue(mailhost)host
• c-gtupdate(entry)
• entry c-gtnextEntry()
• c-gtclose() if c

29
Example Deleting entries

• !/usr/bin/perl5
• use MozillaLDAPConn
• setup global parameters, using Getopt
• srch (mailhosttintin.netscape.com)
• c new MozillaLDAPConn(\ld)
• entry c-gtsearch(base, SUB, srch)
• while (entry)
• c-gtdelete(entry-gtgetDN())
• entry c-gtnextEntry()
• c-gtclose() if c

30
Example Adding an entry

• !/usr/bin/perl5
• use MozillaLDAPConn
• setup global parameters, using Getopt
• ent MozillaLDAPConnnewEntry()
• ent-gtsetDN(uidleif,dcogre,dccom)
• ent-gtobjectclass top, person
• ent-gtaddValue(cn, Leif Hedstrom)
• ent-gtaddValue(sn, Hedstrom)
• ...
• c new MozillaLDAPConn(\ld)
• c-gtadd(ent)
• c-gtclose() if c

31
Case study modattr.pl

• !/usr/bin/perl5
• use GetoptStd
• use MozillaLDAPConn
• use MozillaLDAPUtils
• use strict
• no strict "vars"
• APPNAM "modattr"
• USAGE "APPNAM -dnvW -b base -h host -D
  bind\
• -w pswd -P cert attrvalue filter"
• if (!getopts('adnvWbhDpswP'))
• print "usage APPNAM USAGE\n"
• exit
• ld MozillaLDAPUtilsldapArgs()
• MozillaLDAPUtilsuserCredentials(\ld)
  unless opt_n

32
Case study modattr.pl

• conn new MozillaLDAPConn(\ld)
• die "Couldn't connect to LDAP server ldhost"
  unless conn
• conn-gtsetDefaultRebindProc(ldbind,
  ldpswd)
• (change, search) _at_ARGV
• if ((change eq "") (search eq ""))
• print "usage APPNAM USAGE\n"
• exit
• (attr, value) split(//, change, 2)
• entry conn-gtsearch(ldroot, ldscope,
  search)
• while (entry)
• changed 0
• if (opt_d)
• if (defined entry-gtattr)

33
Case study modattr.pl

• if (value)
• changed entry-gtremoveValue(attr,
  value)
• if (changed opt_v)
• print "Removed value from ",
• entry-gtgetDN(), "\n" if opt_v
• else
• delete entry-gtattr
• print "Deleted attribute attr for ",
• entry-gtgetDN(), "\n" if opt_v
• changed 1
• else
• print "No attribute values for attr\n"
• else

34
Case study modattr.pl

• if (!defined(value) !value)
• print "No value provided for the attribute
  attr\n"
• elsif (opt_a)
• changed entry-gtaddValue(attr,
  value)
• if (changed opt_v)
• print "Added attribute to ",
• entry-gtgetDN(), "\n" if opt_v
• else
• entry-gtsetValue(attr, value)
• changed 1
• print "Set attribute for ",
• entry-gtgetDN(), "\n" if opt_v

35
Case study modattr.pl

• if (changed !opt_n)
• conn-gtupdate(entry)
• conn-gtprintError() if conn-gtgetErrorCode()
• entry conn-gtnextEntry()
• conn-gtclose() if conn

36
Using modattr.pl

• Use standard LDAP arguments (-h etc.)
• Use -n to see what would be done (safe)
• Add an attribute value
• modattr.pl -a cnLeif Hedstrom (uidleif)
• modattr.pl -a mailHosttintin (uid)
• Deleting an entire attribute
• modattr.pl -d salary (departmentIS)

37
Using modattr.pl (cont.)

• Deleting an individual attribute value
• modattr.pl -d cnLeif Hedstrom (uidleif)
• modattr.pl -d lBld 4 (uid)
• POD documentation is included with the script,
  for more details.
• pod2text modattr.pl
• pod2html modattr.pl

38
Future directions

• v1.4 soon to be released, v1.3 is currently being
  developed (its a developers branch)
• Tons of ideas
• Modules for LDAP v3 features like controls,
  persistent searches, SASL etc.
• Managing Netscape Console server info via PerLDAP
• Managing LDAP servers, like schema, index

39
Future directions (cont.)

• LDAP group management module
• Configuration module (global configurations)
• New argument parser, to handle all options as
  DS-4.0 clients does
• Still need more help, the OpenSource model hasnt
  really taken off with PerLDAP and the SDKs.

40
Resources

• http//www.mozilla.org/directory/
• http//www.perldap.org/
• http//www.perl.com/
• http//www.ogre.com/stuff/perl5/
• http//www.ogre.com/ldap/
• http//www.mozilla.org/directory/faq/perldap-faq.h
  tml