Welcome to Syncrepl Client’s documentation!

syncrepl_client is a Python module that makes LDAP Syncrepl easy to use.

LDAP Syncrepl allows you to keep up-to-date with an LDAP server, effectively in real time, even without LDAP administrator credentials.

If your LDAP directory is used as the source of truth (or a delegate for the soource of truth), this keeps you informed when something changes. Callbacks—which you write—are triggered by this code when something happens. You can then take appropriate action, such as by inserting into a queue or sending a message over a bus.

What is Syncrepl?

Syncrepl (as described in RFC 4533) is a standard which allows an LDAP server to keep clients in sync with itself. The clients keep track of a “cookie”, an opaque string that the server uses to know how far behind the client is. The LDAP server then “refreshes” the client by sending details of new & changed entries, as well as information on which entries have been deleted. After the refresh is complete, the client is able to keep a long-running connection open to the server, and receive notice as soon as a change happens on the server.

Syncrepl is the way that OpenLDAP uses to implement replication (from a master LDAP server to one or more slaves), but the client does not have to be an OpenLDAP server. In fact, because Syncrepl is layered on top of an ordinary LDAP search, regular LDAP clients—even those with limited access—are able to use Syncrepl to effectively be notified as soon as the results of their search has changed. This includes notification on:

  • New entries that match your search filter.
  • Entries being deleted.
  • Entries, which used to match, no longer matching. This is essentially the same as deletion (at least, it is when you are using a search filter).
  • Existing entries having their attributes or DN changed.

The entries you see, and the changes made to them, are based on the intersection of four things.

  1. The entries currently in the directory.
  2. Your access rights, as determined by your bind DN.
  3. Your search filter.
  4. Your list of requested attributes.

Thanks to the Syncrepl protocol, you don’t have to worry about all of the above. The LDAP server handles the work of figuring out what you can see.

Requirements

syncrepl_client has four major requirements:

  • Python 2.7, or Python 3.3+.

    If you use Python 2.7 or 3.3, you will also need enum34.

    If you plan on doing “refresh and persist” operations (which run for a long time), your Python should support threads.

  • An appropriate Python LDAP library:

    • For Python 2.7, python-ldap 99 or later is needed.
    • For Python 3, pyldap 2.4.37 or later is needed.
  • The pyasn1 module, at least version 0.2.2, and less than version 0.3.1.

    Technically, this is a requirement of python-ldap / pyldap. It is an optional dependency for them, and is only used when using ldap.syncrepl. That makes it a requirement for us.

  • A fast data store, large enough to store a copy of all the LDAP data received, and a corresponding amount of RAM.

  • An LDAP server which supports RFC 4533, and which is keeping track of changes.

    In the case of OpenLDAP, this means following the instructions in Section 18.3.1 of the Admin Guide.

Lots more details are available on the Requirements page.

How to Use

Although you’ll still need to do a fair bit of coding (mainly in Step 1), syncrepl_client is (intentionally) pretty easy to use! Over the life of your code’s execution, you should do these four things:

  1. Create a class which implements the methods defined in BaseCallback This is how you are notified of changes from the LDAP server.
  2. In your main code, import syncrepl_client and instantiate a new Syncrepl object. The instantiation will handle the connection and the search setup.
  3. Call poll() until it returns False. If you’re running single-threaded, set timeout to some positive, non-zero value. Call please_stop() when you want to safely shut down, and then resume calling poll() until it returns False.
  4. Call unbind(). You’re done!

Lots more details are available in the Requirements page, and see demo.py for a simple example.