.. |status| image:: https://img.shields.io/pypi/status/syncrepl_client.svg :target: https://pypi.python.org/pypi/syncrepl-client :alt: Software Status
.. |version| image:: https://img.shields.io/pypi/v/syncrepl_client.svg :target: https://pypi.python.org/pypi/syncrepl-client :alt: Current Version
.. |python| image:: https://img.shields.io/pypi/pyversions/syncrepl_client.svg :target: https://pypi.python.org/pypi/syncrepl-client :alt: Supported Python Versions
.. |license| image:: https://img.shields.io/pypi/l/syncrepl_client.svg :target: https://github.com/akkornel/syncrepl/blob/master/AUTHORS :alt: BSD 3-Clause License
.. |docs| image:: http://readthedocs.org/projects/syncrepl-client/badge/?version=latest :target: http://syncrepl-client.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status
.. |coverity| image:: https://img.shields.io/coverity/scan/12870.svg :target: https://scan.coverity.com/projects/akkornel-syncrepl :alt: Coverity Scan Status
+--------------------+--------------------+-------------------+ | |status| |version| | |python| |license| | |docs| |coverity| | +--------------------+--------------------+-------------------+
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.
.. _LDAP Syncrepl: https://www.openldap.org/doc/admin24/replication.html#LDAP%20Sync%20Replication
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.
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.
.. _RFC 4533: https://datatracker.ietf.org/doc/rfc4533/
Syncrepl is what OpenLDAP uses to implement replication, 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 be efficiently 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.
The entries currently in the directory.
Your access rights, as determined by your bind DN.
Your search filter.
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.
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.
Older versions may be supported. Read more in patches_.
The pyasn1_ module, at least version 0.2.2, and less than version 0.3.1.
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 in the Requirements page_.
.. _enum34: https://bitbucket.org/stoneleaf/enum34 .. _python-ldap: https://www.python-ldap.org .. _pyldap: https://github.com/pyldap/pyldap .. _patches: https://github.com/akkornel/syncrepl/tree/master/patches .. _Section 18.3.1: https://www.openldap.org/doc/admin24/replication.html#Syncrepl .. _Admin Guide: https://www.openldap.org/doc/admin24/index.html .. _the Requirements page: http://syncrepl-client.readthedocs.io/en/latest/requirements.html
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:
Create a class which implements the methods defined in BaseCallback_ This
is how you are notified of changes from the LDAP server.
In your main code, import syncrepl_client and instantiate a new
Syncrepl_ object. The instantiation will handle the connection and the
search setup.
Call poll_ until it returns False. If you're running single-threaded,
set the timeout parameter 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.
Call unbind_. You're done!
Lots more details are available in the Requirements page, and see demo.py
for a simple example.
.. _BaseCallback: http://syncrepl-client.readthedocs.io/en/latest/callbacks.html#syncrepl_client.callbacks.BaseCallback .. _Syncrepl: http://syncrepl-client.readthedocs.io/en/latest/client.html#syncrepl_client.Syncrepl .. _poll: http://syncrepl-client.readthedocs.io/en/latest/client.html#syncrepl_client.Syncrepl.poll .. _please_stop: http://syncrepl-client.readthedocs.io/en/latest/client.html#syncrepl_client.Syncrepl.please_stop .. _unbind: http://syncrepl-client.readthedocs.io/en/latest/client.html#syncrepl_client.Syncrepl.unbind .. _demo.py: https://github.com/akkornel/syncrepl/blob/master/demo.py
The contents of this repository are copywrited according to the contents of the
AUTHORS_ file.
The code is made available under the BSD 3-Clause License.
Other code is made available under the Creative Commons CC0 Public Domain Dedication.
Documentation is made available under the Creative Commons Attribution-ShareAlike 4.0 International Public License (the CC BY-SA License). Code contained within documentation is made available under both the BSD 3-Clause License, and the CC BY-SA License.
To identify the license for any particular file, refer to the contents of the file.
The text of the BSD 3-Clause License is reproduced in the file LICENSE.md.
The text of the other licenses may be found in the file LICENSE_others.md.
Note that all three licenses are equally important, but are kept in a separate
files to aid GitHub's irepository license-detection mechanisms.
.. _AUTHORS: https://github.com/akkornel/syncrepl/blob/master/AUTHORS .. _LICENSE.md: https://github.com/akkornel/syncrepl/blob/master/LICENSE.md .. _LICENSE_others.md: https://github.com/akkornel/syncrepl/blob/master/LICENSE_others.md
FAQs
An easier-to-use LDAP syncrepl client
We found that syncrepl-client demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
