Add documentation and copyrights

1 files changed, 143 insertions, 0 deletions

diff --git a/doc/slapi-dnsnotify.8 b/doc/slapi-dnsnotify.8
new file mode 100644
index 0000000..c75d1bf
--- /dev/null
+++ b/doc/slapi-dnsnotify.8
@@ -0,0 +1,143 @@
+.\" 
+.\" 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