D-Bus plugin for watching changes on nodes
------------------------------------------

This postoperation plugin can watch changes on specified nodes with a given 
scope. Only successful operations are processed. Matched operations are 
exported via D-Bus signals to the system bus. The plugin currently supports 
watching add, remove and modify operations.

The exported messages on the D-Bus contain the DN of the matched item.
Moreover, list of all (or selected) attributes is contained in the exported
messages for add operations. This behavior can be changed using the 
dbus-plugin-attr and dbus-plugin-attr-all attributes. The watched node needs 
dbus-plugin-enabled set to yes to work. By default the watching is disabled.

The configuration of the plugin is stored in LDAP under
cn=D-Bus Plugin,cn=plugins,cn=config

The configurations of the watched nodes are stored in subtree nodes of the plugin 
configuration. For example to watch all add operations on whole subtree of
ou=People,dc=example,dc=com use the configuration below. Attributes mail and 
roomNumber will be exported as strings in addtion to matched item DN.

dn: cn=add,cn=D-Bus Plugin,cn=plugins,cn=config
objectclass: top
objectclass: extensibleObject
cn: add
dbus-plugin-type: add
dbus-plugin-target: ou=People,dc=example,dc=com
dbus-plugin-scope: subtree
dbus-plugin-attr: mail, roomNumber
dbus-plugin-attr-all: no
dbus-plugin-signal: DeletePeopleAdd
dbus-plugin-enabled: yes

The plugin will reload its configuration automatically if it detects
changes in its configuration. No sever restart is needed.

The examples in this readme use tools from these packages:
qt (qdbus)
openldap-clients (ldapadd, etc.)
dbus (dbus-monitor)


Installation
------------
1. apply provided patch on the master branch of ds.git

# git checkout 5285304756536917d1c6e8b708a68853f2a997e8
# git apply 0001-Added-D-Bus-plugin.patch

2. copy plugin D-Bus configuration file
Please note that the configuration expects nobody user as the owner of this
service. If you use other user please modify the configuration file. By default
all users in wheel group are permitted to access the plugin's methods and signals.

# cd ldap/servers/plugins/dbusplugin/config/
# cp dbusplugin.conf /etc/dbus-1/system.d/dbusplugin.conf

3. build, install and setup server
Important note:
 - run autogen.sh before building and install dbus-devel package

# ./autogen.sh
# ./configure --with-openldap
# make && make install
# /opt/dirsrv/sbin/setup-ds.pl
# /opt/dirsrv/sbin/stop-dirsrv

4. apply updated to the server
This will bring in D-Bus plugin configuration. Please use Offline method
for updating.
# /opt/dirsrv/sbin/setup-ds.pl --update

4. check if plugin works
# qdbus --system org.fedoraproject.ds.dbusplugin / List
No nodes


Usage
-----
1. Add examples for watching nodes
You may need to update the config/example.ldif with your desired configuration and use
correct LDAP manager instead of cn=manager.

# cd ldap/servers/plugins/dbusplugin/config/
# cat config/example.ldif | ldapadd -D  -W

2. List all available watched nodes
# qdbus --system org.fedoraproject.ds.dbusplugin / List

Plugin:     cn=add,cn=D-Bus Plugin,cn=plugins,cn=config
Enabled:    yes
Operation:  add
Target:     ou=People,dc=example,dc=com
Scope:      subtree
Interface:  org.fedoraproject.ds.dbusplugin
Signal:     DeletePeopleAdd
Attributes: mail roomNumber 
All attr:   false

Plugin:     cn=modify,cn=D-Bus Plugin,cn=plugins,cn=config
Enabled:    yes
Operation:  modify
Target:     ou=People,dc=example,dc=com
Scope:      base
Interface:  org.fedoraproject.ds.dbusplugin
Signal:     ModifyPeopleBase
Attributes: none
All attr:   false

Plugin:     cn=delete,cn=D-Bus Plugin,cn=plugins,cn=config
Enabled:    yes
Operation:  delete
Target:     ou=People,dc=example,dc=com
Scope:      onelevel
Interface:  org.fedoraproject.ds.dbusplugin
Signal:     DeletePeopleOnelevel
Attributes: none

3. List all available methods/signals
# qdbus --system org.fedoraproject.ds.dbusplugin /
method QString org.freedesktop.DBus.Introspectable.Introspect()
signal void org.fedoraproject.ds.dbusplugin.DeletePeopleAdd(QString operation, QString dn)
signal void org.fedoraproject.ds.dbusplugin.DeletePeopleOnelevel(QString operation, QString dn)
method void org.fedoraproject.ds.dbusplugin.List()
signal void org.fedoraproject.ds.dbusplugin.ModifyPeopleBase(QString operation, QString dn)

4. Try to monitor D-Bus and add/remove/modify some items under ou=People,dc=example,dc=com
Example below shows D-Bus message sent to signal interface
org.fedoraproject.ds.dbusplugin.AddPeopleSubtree of the plugin after adding 
record uid=jvedder,ou=People,dc=example,dc=com.

signal sender=:1.451 -> dest=(null destination) serial=756 path=/org/fedoraproject/ds/dbusplugin/dpobject; interface=org.fedoraproject.ds.dbusplugin; member=AddPeopleSubtree
   string "uid=jvedder,ou=People,dc=example,dc=net"
   string "mail: jvedder@example.com"
   string "roomNumber: 3445"


Future features
---------------
1. D-Bus methods for adding/removing watched nodes

2. More details exported to D-Bus for delete, modify, modifyrdn operations

3. Search operation watch

4. Filter on any operation


Known issues
------------
1. The signal introspect item has only one exported parameter shown. This does not correspond to the real count of exported parameters (for the ADD operation only) in the output of 
qdbus --system org.fedoraproject.ds.dbusplugin /
This is more a cosmetic issue.

-- 
version 0.1