.\" 
.\" Copyright (c) 2008, Stef Walter
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without 
.\" modification, are permitted provided that the following conditions 
.\" are met:
.\" 
.\"     * Redistributions of source code must retain the above 
.\"       copyright notice, this list of conditions and the 
.\"       following disclaimer.
.\"     * 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.
.\"     * The names of contributors to this software may not 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 OWNER 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.
.\" 
.\"
.\" CONTRIBUTORS
.\"  Stef Walter <stef@memberwebs.com>
.\"
.Dd June, 2008
.Dt slapi-dnsnotify
.Os slapi-dnsnotify 
.Sh NAME
.Nm slapi-dnsnotify
.Nd is a plugin for an LDAP based DNS server which notifies slave name 
servers when a zone is changed. 
.Sh DESCRIPTION
.Nm slapi-dnsnotify
is a plugin for OpenLDAP or other LDAP servers. It watches for changes in 
the serial number of a DNS zone stored in the LDAP server, and notifies DNS 
slave servers to refresh their copy of the zone. 
.Pp
It can also increment the serial number of a zone whenever changes in that 
zone are made.
.Sh DETAILS
This is a SLAPI 'postoperation' plugin. The entry point is 'plugin_init'. 
See below for an example of how to configure it. 
.Pp
An LDAP entry is assumed to be a zone if it has an 
.Em sOARecord
attribute. The exact name of the attribute can be controlled with the 
.Em soa-attribute
option. The information about the zone, such as name servers and zone name are 
retrieved from the same LDAP entry, that is the one with the SOA attribute 
on it.  
.Pp
Notification requests are handled by the 
.Xr notify-dns-slaves 5
tool. The notifications are not sent immediately, and multiple notifications 
that occur close together are combined into a single notification. See the 
.Em notify-delay
option.
.Pp
To increment the serial number of a zone automatically whenever something in 
the zone changes, use the 
.Em enable-auto-serial
option. All LDAP entries beneath the entry with the SOA attribute are assumed 
to be part of that zone for purposes of incrementing the serial number. 
.Sh OPTIONS
Options are specified one after another with spaces separating them. If an 
option requires a value, then separate the name and value with a equal sign.
eg: name=value
.Bl -tag -width Fl
.It Cd base-dn
The base DN in the LDAP tree where DNS zones are stored.
.Pp
[ Required ]
.It Cd disable-notify
Disable all notification of DNS slave servers.
.Pp
[ Optional ]
.It Cd enable-auto-serial
Automatically update the serial number in the DNS zones when any LDAP 
entries underneath the zone entry are modified.
.Pp
[ Optional ]
.It Cd notify-delay
The number of seconds to delay before sending notifications to DNS slave 
servers. This allows multiple notifications to be coalesced into one.
.Pp
[ Default:
.Em 5
]
.It Cd ns-attribute
The name of the LDAP attributeType that contains the DNS NS record for a zone.
.Pp
[ Default:
.Em nSRecord
]
.It Cd soa-attribute
The name of the LDAP attributeType that contains the DNS SOA record for a zone. 
.Pp
[ Default: 
.Em sOARecord
]
.It Cd zone-attribute
The name of the LDAP attributeType that contains the complete name of a zone.
.Pp
[ Default:
.Em associatedDomain
]
.El
.Sh EXAMPLES
Here is an example of how to configure this plugin with OpenLDAP, using an LDAP 
base DN of 
.Em dc=example,dc=com
and with automatic incrementing of the zone serial number and a notification 
delay of 10 seconds.
.Pp
The following would go into your 
.Xr slapd.conf 5
file: 
.Bd -literal -offset indent
plugin postoperation \\
	/usr/local/lib/slapi-dnsnotify.so plugin_init \\
	notify-delay=10 base-dn=ou=web,dc=ws,dc=local \\
	enable-auto-serial 
.Ed
.Pp
The above may all be specified on one line. The backslashes at the end make 
it more readable and maintainable.  
.Sh SEE ALSO
.Xr slapd.conf 5
.Xr notify-dns-slaves 1
.Sh AUTHOR
.An Stef Walter Aq stef@memberwebs.com