path: root/README.md

LDAP Utilities
==============

Copyright (c) 2012, 2015, 2019, 2020 David M. Syzdek <david@syzdek.net>

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

   1. Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.

   2. Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.

   3. Neither the name of the copyright holder nor the names of its
      contributors may be used to endorse or promote products derived from
      this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


Contents
--------

   * Overview
   * Software Requirements
   * Utilities
     - ldap2csv
     - ldap2json
     - ldapdebug
     - ldapdn2str
     - ldapinfo
     - ldapschema
     - ldaptree
   * Source Code
   * Package Maintence Notes


Overview
==========

This package contains miscellaneous utilties to assist in fullfilling requests
for data and in performing maintenance on LDAP servers.  When applicable, the
corresponding command line switches from the OpenLDAP tools were used in this
package.


Software Requirements
=====================

   * GNU GCC 4.2.1
   * GNU Libtool 2.4
   * GNU Autoconf 2.65
   * GNU Automake 1.11.1
   * Git 1.7.2.3
   * OpenLDAP 2.4.X


Utilities
=========

ldap2csv
--------

ldap2csv is a shell utilty which performs an LDAP search and prints the results
in CSV format.  ldap2csv requires that a search filter and at least 1 attribute
be specified on the CLI.  Each specified attribute will be used as a field
in the CSV file.  Multiple values for a given attribute are sorted and separated
by a pipe ('|') chracter. Each double quote ('"') character found in a returned
value will be replaced with a single quote ('\'') chracter. Each pipe ('|')
character found in a returned value will be replaced with a colon (':')
character.

ldap2csv supports psuedo attributes which return the DN of returned entries in
various formats.  The following are the supported psuedo attributes and examples
of their format:

   * `dn` (distinguished name of entry)
   * `dce` (DCE-style distinguished name)
   * `adc` (Active Directory canonical name)
   * `rdn` (relative distinguished name of entry)
   * `ufn` (User Friendly Name of DN)

Example usage:

      $ ldap2csv -LLL -x -b o=internet -S sn '(uid=*)' uid givenname sn mail title rdn
      "uid","givenname","sn","mail","title","rdn"
      "dnullman","Devian","Nullman","noreply@example.com","Linux Device : /dev/null","uid=dnullman"
      "jdough","John","Dough","doughboy42@example.com","'Dough' Master","uid=jdough"
      "syzdek","David M.","Syzdek","david@syzdek.net","Slackware Linux Administrator","uid=syzdek"
      $

Example of the same search using `ldapsearch`:

      $ ldapsearch -LLL -x -b o=internet -S sn '(uid=*)' uid givenname sn mail title
      dn: uid=dnullman,ou=People,dc=example,dc=net,o=internet
      uid: dnullman
      givenname: Devian
      sn: Nullman
      mail: noreply@example.com
      title: Linux Device | /dev/null
       
      dn: uid=jdough,ou=People,dc=example,dc=net,o=internet
      uid: jdough
      givenname: John
      sn: Dough
      mail: doughboy42@example.com
      title: "Dough" Master
      
      dn: uid=syzdek,ou=People,dc=syzdek,dc=net,o=internet
      uid: syzdek
      givenname: David M.
      sn: Syzdek
      mail: david@syzdek.net
      title: Slackware Linux Administrator


ldap2json
---------

ldap2json is a shell utilty which performs an LDAP search and prints the results
in JSON format.

ldap2json supports psuedo attributes which return the DN of returned entries in
various formats.  The following are the supported psuedo attributes and examples
of their format:

   * `dn` (distinguished name of entry)
   * `dce` (DCE-style distinguished name)
   * `adc` (Active Directory canonical name)
   * `rdn` (relative distinguished name of entry)
   * `ufn` (User Friendly Name of DN)

Example usage:

      $ ldap2json -LLL -x -b o=internet -S sn '(uid=*)' uid givenname sn mail title rdn
      [
         {
            "uid": "jdough",
            "givenname": "John",
            "sn": "Dough",
            "mail": "doughboy42@example.com",
            "title": "'Dough' Master",
            "rdn": "uid=jdough"
         },
         {
            "uid": "dnullman",
            "givenname": "Devian",
            "sn": "Nullman",
            "mail": "noreply@example.com",
            "title": "Linux Device : /dev/null",
            "rdn": "uid=dnullman"
         },
         {
            "uid": "syzdek",
            "givenname": "David M.",
            "sn": "Syzdek",
            "mail": "david@syzdek.net",
            "title": "Slackware Linux Administrator",
            "rdn": "uid=syzdek"
         }
      ]
      $

Example of the same search using `ldapsearch`:

      $ ldapsearch -LLL -x -b o=internet -S sn '(uid=*)' uid givenname sn mail title
      dn: uid=dnullman,ou=People,dc=example,dc=net,o=internet
      uid: dnullman
      givenname: Devian
      sn: Nullman
      mail: noreply@example.com
      title: Linux Device | /dev/null

      dn: uid=jdough,ou=People,dc=example,dc=net,o=internet
      uid: jdough
      givenname: John
      sn: Dough
      mail: doughboy42@example.com
      title: "Dough" Master

      dn: uid=syzdek,ou=People,dc=syzdek,dc=net,o=internet
      uid: syzdek
      givenname: David M.
      sn: Syzdek
      mail: david@syzdek.net
      title: Slackware Linux Administrator


ldapdebug
---------

ldapdebug is a utility which initiates a connection the an LDAP server
and optionally binds to the LDAP server.  Once the LDAP session has been
established, the utility will display the values of various options
available from `ldap_get_option()`.  This utility is useful for debugging
`ldap.conf` and `.ldaprc` files.

ldapdebug is not installed by default.  To enable building and installing
ldapdebug, the flag `--enable-ldapdebug` must be passed to configure.


ldapdn2str
----------

ldapdn2str parses LDAP distinguished names and prints the parsed DN using the
requested format.  The OpenLDAP function ldap_dn2str() is used to perform
the formatting the DN presentation for `dn`, `dce`, `adc`, and `ufn`.

The following are example of the output presentations available:

   * dn: distinguished name
     - `uid=dnullman,ou=People,dc=example,dc=net,o=internet`
     - `uid=jdough,ou=People,dc=example,dc=net,o=internet`
     - `uid=syzdek,ou=People,dc=syzdek,dc=net,o=internet`
     - `uid=administrator,ou=People,dc=foo,dc=org`
  
   * dce: DCE-style DN
     - `/o=internet/dc=net/dc=example/ou=People/uid=dnullman`
     - `/o=internet/dc=net/dc=example/ou=People/uid=jdough`
     - `/o=internet/dc=net/dc=syzdek/ou=People/uid=syzdek`
     - `/dc=org/dc=foo/ou=People/uid=administrator`

   * adc: Active Directory canonical name
     - `internet/net/example/People/dnullman/`
     - `internet/example.net/People/jdough`
     - `internet/syzdek.net/People/syzdek`
     - `foo.org/People/administrator`

   * rdn: relative DN
     - `uid=dnullman`
     - `uid=jdough`
     - `uid=syzdek`
     - `uid=administrator`

   * ufn: User Friendly Name of DN
     - `dnullman, People, syzdek, net, internet`
     - `jdough, People, example, net, internet`
     - `syzdek, People, example, net, internet`
     - `administrator, People, foo.org`

   * idn: inverted distinguished name
     - `o=internet,dc=net,dc=example,ou=People,uid=dnullman`
     - `o=internet,dc=net,dc=example,ou=People,uid=jdough`
     - `o=internet,dc=net,dc=syzdek,ou=People,uid=syzdek`
     - `dc=org,dc=foo,ou=People,uid=administrator`


ldapinfo
--------

ldapinfo is a shell utilty which queries the LDAP server for server information and
displays the information in human readable form.

The following example uses a priviledged bind DN to obtain server stats:

      $ ldapinfo -W
      Enter LDAP Password:
      Vendor name:                 OpenLDAP
      Vendor version:              slapd 2.4.46 (Dec  5 2018 16:21:32)
      LDAP version:                3
      Subschema Subentry:          cn=Subschema
      Configuration context:       cn=config
      Monitoring context:          cn=Monitor

      Schema:                      ldapSyntaxes: 32
                                   matchingRules: 37
                                   matchingRuleUse: 31
                                   attributeTypes: 693
                                   objectClasses: 145

      Operations:                  Bind initiated: 529432; completed 529432
                                   Unbind initiated: 378252; completed 378252
                                   Search initiated: 3900266; completed 3900265
                                   Compare initiated: 6254; completed 6254
                                   Modify initiated: 0; completed 0
                                   Modrdn initiated: 0; completed 0
                                   Add initiated: 0; completed 0
                                   Delete initiated: 1; completed 1
                                   Abandon initiated: 174; completed 174
                                   Extended initiated: 439445; completed 439445

      Connections:                 Max File Descriptors: 1024
                                   Total: 459982
                                   Current: 143

      Naming contexts:             cn=config (config)
                                   dc=example,dc=org (mdb) [ memberof ppolicy refint syncprov ]
                                   o=subscribers (mdb) [ memberof ppolicy refint syncprov ]
                                   o=metadata (mdb) [ syncprov ]
                                   o=registry (mdb) [ memberof ppolicy refint syncprov ]

      Supported controls:          1.2.826.0.1.3344810.2.3 (Matched Values Control)
                                   1.2.840.113556.1.4.319 (LDAP Simple Paged Results Control)
                                   1.3.6.1.1.12 (Assertion Control)
                                   1.3.6.1.1.13.1 (LDAP Pre-read Control)
                                   1.3.6.1.1.13.2 (LDAP Post-read Control)
                                   1.3.6.1.1.22 (LDAP Don't Use Copy Control)
                                   1.3.6.1.4.1.4203.1.10.1 (Subentries)
                                   1.3.6.1.4.1.4203.1.9.1.1 (LDAP Content Synchronization Control)
                                   2.16.840.1.113730.3.4.18 (Proxy Authorization Control)
                                   2.16.840.1.113730.3.4.2 (ManageDsaIT)

      Supported extension:         1.3.6.1.1.8 (Cancel Operation)
                                   1.3.6.1.4.1.1466.20037 (StartTLS)
                                   1.3.6.1.4.1.4203.1.11.1 (Modify Password)
                                   1.3.6.1.4.1.4203.1.11.3 (Who am I?)

      Supported features:          1.3.6.1.1.14 (Modify-Increment)
                                   1.3.6.1.4.1.4203.1.5.1 (All Op Attrs)
                                   1.3.6.1.4.1.4203.1.5.2 (OC AD Lists)
                                   1.3.6.1.4.1.4203.1.5.3 (True/False filters)
                                   1.3.6.1.4.1.4203.1.5.4 (Language Tag Options)
                                   1.3.6.1.4.1.4203.1.5.5 (Language Range Options)

      Supported SASL mechanisms:   CRAM-MD5
                                   DIGEST-MD5
                                   LOGIN
                                   OTP
                                   PLAIN
                                   SCRAM-SHA-1


ldapschema
----------

ldapschema is a shell utility for searching and displaying the schema of an LDAP
server.  The utility can run in either lint, list, search, or dump mode. In lint
mode the utility will report schema errors it encountered. In list mode, the
utility will list the OID and NAME/DESC of the object types specified. In dump
mode the utility will display detailed information about all objects in the
schema which it understands. In search mode the utility will display detailed
information of the objects requested and any related objects such as superiors.

The following is an example of a schema search for an objectclass:

      $ ldapschema  2.5.6.9
      objectClass:        2.5.6.9
         name(s):         groupOfNames
         description:     RFC2256: a group of names (DNs)
         usage:           abstract
         superior(s):     top
         may:             businessCategory
                          description
                          o
                          ou
                          owner
                          seeAlso
         must:            cn
                          member
         inherited must:  objectClass
         definition:      (  2.5.6.9
                             NAME 'groupOfNames'
                             DESC 'RFC2256: a group of names (DNs)'
                             SUP top
                             STRUCTURAL
                             MUST
                             (  member $ cn
                             )
                             MAY
                             (  businessCategory $ seeAlso $
                                owner $ ou $ o $ description
                             )
                          )


      objectClass:        2.5.6.0
         name(s):         top
         description:     top of the superclass chain
         usage:           abstract
         must:            objectClass
         definition:      (  2.5.6.0
                             NAME 'top'
                             DESC 'top of the superclass chain'
                             ABSTRACT
                             MUST objectClass
                          )

The following is an example of a schema search for an attributeType:

      $ ldapschema  pwdChangedTime
      attributeType:      1.3.6.1.4.1.42.2.27.8.1.16
         name(s):         pwdChangedTime
         description:     The time the password was last changed
         single value:    yes
         readable:        yes
         no user mod:     yes
         usage:           directoryOperation
         syntax:          1.3.6.1.4.1.1466.115.121.1.24 ( Generalized Time )
         data class:      ASCII
         common abnf:     no
         schema abnf:     no
         abnf:            GeneralizedTime = century year month day hour
                                               [ minute [ second / leap-second ] ]
                                               [ fraction ]
                                               g-time-zone

                          century = 2(%x30-39) ; "00" to "99"
                          year    = 2(%x30-39) ; "00" to "99"
                          month   =   ( %x30 %x31-39 ) ; "01" (January) to "09"
                                    / ( %x31 %x30-32 ) ; "10" to "12"
                          day     =   ( %x30 %x31-39 )    ; "01" to "09"
                                    / ( %x31-32 %x30-39 ) ; "10" to "29"
                                    / ( %x33 %x30-31 )    ; "30" to "31"
                          hour    = ( %x30-31 %x30-39 ) / ( %x32 %x30-33 ) ; "00" to "23"
                          minute  = %x30-35 %x30-39                        ; "00" to "59"

                          second      = ( %x30-35 %x30-39 ) ; "00" to "59"
                          leap-second = ( %x36 %x30 )       ; "60"

                          fraction        = ( DOT / COMMA ) 1*(%x30-39)
                          g-time-zone     = %x5A  ; "Z"
                                            / g-differential
                          g-differential  = ( MINUS / PLUS ) hour [ minute ]
                          MINUS           = %x2D  ; minus sign ("-")
                          DOT     = %x2E ; period (".")
                          COMMA   = %x2C ; comma (",")
                          PLUS    = %x2B ; plus sign ("+")
         definition:      (  1.3.6.1.4.1.42.2.27.8.1.16
                             NAME 'pwdChangedTime'
                             DESC 'The time the password was last changed'
                             EQUALITY generalizedTimeMatch
                             ORDERING generalizedTimeOrderingMatch
                             SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
                             SINGLE -VALUE NO -USER -MODIFICATION
                             USAGE directoryOperation
                          )


ldaptree
--------

ldaptree is a shell utilty which performs an LDAP search and prints the results
as either an ASCII graph or a bulletted list.  By default the utilty does not
retrieve any attributes from LDAP servers, however if a search filter and
attribute list are provided as command line arguments, then the attribute values
will be displayed inline with the results.  The utility utilizes additional long
options to customize the output of either the ASCII graph or the bulletted list.

ASCII graph eexample with compact output and no leaf nodes:

      $ ldaptree -x -b o=internet --noleafs --compact
      #
      # base: o=internet with scope subtree
      # filter: (objectclass=*)
      #
      +--dc=net, o=internet
          +--dc=example
          |  +--ou=Groups
          |  \--ou=People
          \--dc=syzdek
             +--ou=Groups
             \--ou=People

ASCII graph example with attribute values:

      $ ldaptree -LLL -x -b o=internet '(objectclass=*)' givenname sn mail member description
      +--dc=net, o=internet
          +--dc=example
          |  +--ou=Groups
          |  |  +--cn=lug
          |  |  |     description: Linux Users' Group
          |  |  |     member: uid=dnullman,ou=People,dc=example,dc=net,o=internet
          |  |  |     member: uid=doughboy42,ou=People,dc=example,dc=net,o=internet
          |  |  |
          |  |  \--cn=foodie
          |  |        description: People obsessed with good food
          |  |        member: uid=doughboy42,ou=People,dc=example,dc=net,o=internet
          |  |
          |  \--ou=People
          |     +--uid=dnullman
          |     |     sn: Nullman
          |     |     givenName: Devian
          |     |     mail: noreply@example.com
          |     |
          |     \--uid=jdough
          |           sn: Dough
          |           givenName: John
          |           mail: doughboy42@example.com
          |
          \--dc=syzdek
             +--ou=Groups
             \--ou=People
                \--uid=syzdek
                      sn: Syzdek
                      givenName: David M.
                      mail: david@syzdek.net

Bulleted list example:

      $ ldaptree -x -b o=internet --style=bullets --compact '(objectclass=*)' givenname sn \
      > mail member description
      * dc=net, o=internet
        * dc=example
          * ou=Groups
            * cn=lug
              * Attributes
                - description: Linux Users' Group
                - member: uid=dnullman,ou=People,dc=example,dc=net,o=internet
                - member: uid=doughboy42,ou=People,dc=example,dc=net,o=internet
            * cn=foodie
              * Attributes
                - description: People obsessed with good food
                - member: uid=doughboy42,ou=People,dc=example,dc=net,o=internet
          * ou=People
            * uid=dnullman
              * Attributes
                - sn: Nullman
                - givenName: Devian
                - mail: noreply@example.com
            * uid=jdough
                - sn: Dough
                - givenName: John
                - mail: doughboy42@example.com
        * dc=syzdek
          * ou=Groups
          * ou=People
            * uid=syzdek
              * Attributes
                - sn: Syzdek
                - givenName: David M.
                - mail: david@syzdek.net


Source Code
===========

The source code for this project is maintained using git
(http://git-scm.com).  The following contains information to checkout the
source code from the git repository.

Browse Source:

   * https://github.com/bindle/ldap-utils
   * https://github.com/bindle/ldap-utils.xcodeproj

Git URLs:

   * https://github.com/bindle/ldap-utils.git
   * https://github.com/bindle/ldap-utils.xcodeproj.git

Downloading Source:

      $ git clone git://github.com/bindle/ldap-utils.git
      $ git clone git://github.com/bindle/ldap-utils.xcodeproj.git \
                  ldap-utils/ldap-utils.xcodeproj

Preparing Source:

      $ cd ldap-utils
      $ ./autogen.sh

Compiling Source:

      $ cd build
      $ ./configure
      $ make && make install

For more information on building and installing using configure, please
read the INSTALL file.

Git Branches:

   * master - Current release of packages.
   * next   - changes staged for next release
   * pu     - proposed updates for next release
   * xx/yy+ - branch for testing new changes before merging to 'pu' branch


Package Maintence Notes
=======================

This is a collection of notes for developers to use when maintaining this
package.

New Release Checklist:

   - Switch to 'master' branch in Git repository.
   - Update version in configure.ac.
   - Update date and version in ChangeLog.
   - Commit configure.ac and ChangeLog changes to repository.
   - Create tag in git repository:

           $ git tag -s v${MAJOR}.${MINOR}

   - Push repository to publishing server:

           $ git push --tags origin master:master next:next pu:pu

Creating Source Distribution Archives:

      $ ./configure
      $ make update
      $ make distcheck
      $ make dist-bzip2
      $ make dist-xz