From 95e306046647dce6b5bebf9c237d6fa6b68efaee Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Wed, 2 Jul 2008 21:25:47 +0000 Subject: Add documentation and copyrights --- doc/Makefile.am | 10 +++ doc/man2html.pl | 230 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/notify-dns-slaves.1 | 86 ++++++++++++++++++ doc/slapi-dnsnotify.8 | 143 ++++++++++++++++++++++++++++++ 4 files changed, 469 insertions(+) create mode 100644 doc/Makefile.am create mode 100755 doc/man2html.pl create mode 100644 doc/notify-dns-slaves.1 create mode 100644 doc/slapi-dnsnotify.8 (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..a5c96b8 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,10 @@ + +man_MANS = slapi-dnsnotify.8 + +# Simple way to make docs +html: + perl man2html.pl slapi-dnsnotify.8 > slapi-dnsnotify.8.html + +EXTRA_DIST = \ + man2html.pl \ + ${man_MANS} diff --git a/doc/man2html.pl b/doc/man2html.pl new file mode 100755 index 0000000..a6a7c3f --- /dev/null +++ b/doc/man2html.pl @@ -0,0 +1,230 @@ +#!/usr/bin/perl + +# TODO: We need to make this more resilient +# currently expects args without enforcing + +$FIL = $NAM = $SEC = @ARGV[0]; + +$NAM =~ s/^([^.]+)\..+$/$1/; +$SEC =~ s/^.+\.([^.]+)$/$1/; + +$command = "groff"; +@args = split(" ", "-Tascii -mdoc $FIL"); + +$enable_include_links = 0; + +man($NAM, $SEC); + +sub man { + local($name, $section) = @_; + local($_, $title, $head, *MAN); + local($html_name, $html_section, $prefix); + local(@manargs); + local($query) = $name; + + # $section =~ s/^([0-9ln]).*$/$1/; + $section =~ tr/A-Z/a-z/; + + $prefix = "Man "; + if ($alttitle) { + $prefix = ""; + $title = &encode_title($alttitle); + $head = &encode_data($alttitle); + } elsif ($section) { + $title = &encode_title("${name}($section)"); + $head = &encode_data("${name}($section)"); + } else { + $title = &encode_title("${name}"); + $head = &encode_data("${name}"); + } + + print &html_header("$title"); + print "

Man Page: ${title}

"; + print "

\n";
+
+    $html_name = &encode_data($name);
+    $html_section = &encode_data($section);
+
+    #print Dumper($sectionpath);
+    #print "yy $section yy $manpath\n";
+    if ($name =~ /^\s*$/) {
+        print "Empty input, no man page given.\n";
+        return;
+    }
+
+    if (index($name, '*') != -1) {
+        print "Invalid character input '*': $name\n";
+        return;
+    }
+
+    if ($section !~ /^[0-9ln]\w*$/ && $section ne '') {
+        print "Sorry, section `$section' is not valid\n";
+        return;
+    }
+
+    if (!$section) {
+        if ($sectionpath->{$manpath}) {
+            $section = "-S " . $sectionpath->{$manpath}{'path'};
+        } else {
+            $section =  '';
+        }
+    } else {
+        if ($sectionpath->{$manpath}{$section}) {
+            $section = "-S " . $sectionpath->{$manpath}{$section};
+        } else {
+            $section = "-S $section";
+        }
+    }
+
+    # print "X $command{'man'} @manargs -- x $name x\n";
+    &proc(*MAN, $command, @args) ||
+        &mydie ("$0: open of $command{'man'} command failed: $!\n");
+    if (eof(MAN)) {
+        # print "X $command{'man'} @manargs -- x $name x\n";
+        print "Sorry, no data found for `$html_name" .
+                ($html_section ? "($html_section)": '') . "'.\n";
+        return;
+    }
+
+    local($space) = 1;
+    local(@sect);
+    local($i, $j);
+    while() {
+        # remove tailing white space
+        if (/^\s+$/) {
+            next if $space;
+            $space = 1;
+        } else {
+            $space = 0;
+        }
+
+        $_ = &encode_data($_);
+        if($enable_include_links &&
+           m,()?\#include()?\s+()?\<\;(.*\.h)\>\;()?,) {
+            $match = $4; ($regexp = $match) =~ s/\./\\\./;
+            s,$regexp,\$match\,;
+        }
+        /^\s/ &&                         # skip headers
+            s,((<[IB]>)?[\w\_\.\-]+\s*()?\s*\(([1-9ln][a-zA-Z]*)\)),&mlnk($1),oige;
+
+        # detect E-Mail Addreses in manpages
+        if (/\@/) {
+            s/([a-z0-9_\-\.]+\@[a-z0-9\-\.]+\.[a-z]+)/$1<\/A>/gi;
+        }
+
+        # detect URLs in manpages
+        if (m%tp://%) {
+            s,((ftp|http)://[^\s<>\)]+),$1,gi;
+        }
+
+        if (/^\S+/ && m%^([^<]+)%) {
+            $i = $1; $j = &encode_url($i);
+            s%^([^<]+)%$i%;
+            push(@sect, $1);
+        }
+        print;
+    }
+    close(MAN);
+
+    print "   [ back | home ]";
+    print "\n";
+    print "\n";
+
+    # Sleep 0.35 seconds to avoid DoS attacs
+    select undef, undef, undef, 0.35;
+}
+
+# encode unknown data for use in ...</TITILE>
+sub encode_title {
+    # like encode_url but less strict (I couldn't find docs on this)
+    local($_) = @_;
+    s/([\000-\031\%\&\<\>\177-\377])/sprintf('%%%02x',ord($1))/eg;
+    $_;
+}
+
+# encode unknown data for use in a URL <A HREF="...">
+sub encode_url {
+    local($_) = @_;
+    # rfc1738 says that ";"|"/"|"?"|":"|"@"|"&"|"=" may be reserved.
+    # And % is the escape character so we escape it along with
+    # single-quote('), double-quote("), grave accent(`), less than(<),
+    # greater than(>), and non-US-ASCII characters (binary data),
+    # and white space.  Whew.
+    s/([\000-\032\;\/\?\:\@\&\=\%\'\"\`\<\>\177-\377 ])/sprintf('%%%02x',ord($1))/eg;
+    s/%20/+/g;
+    $_;
+}
+# encode unknown data for use inside markup attributes <MARKUP ATTR="...">
+sub encode_attribute {
+    # rfc1738 says to use entity references here
+    local($_) = @_;
+    s/([\000-\031\"\'\`\%\&\<\>\177-\377])/sprintf('\&#%03d;',ord($1))/eg;
+    $_;
+}
+# encode unknown text data for using as HTML,
+# treats ^H as overstrike ala nroff.
+sub encode_data {
+    local($_) = @_;
+    local($str);
+
+    # Escape &, < and >
+    s,\010[><&],,g;
+    s/\&/\&\;/g;
+    s/\</\<\;/g;
+    s/\>/\>\;/g;
+
+    s,((_\010.)+),($str = $1) =~ s/.\010//g; "<I>$str</I>";,ge;
+    s,(.\010)+,$1,g;
+
+    if (!s,((.\010.)+\s+(.\010.)+),($str = $1) =~ s/.\010//g; "<B>$str</B>";,ge) {
+        s,((.\010.)+),($str = $1) =~ s/.\010//g; "<B>$str</B>";,ge;
+    }
+
+    s,.\010,,g;
+
+    $_;
+}
+
+sub html_header {
+    return qq{<HTML>
+<HEAD>
+<TITLE>$_[0]
+
+
+
+
+
+\n\n};
+}
+
+sub mlnk {
+    local($matched) = @_;
+    return qq{$matched};
+}
+
+sub proc {
+    local(*FH, $prog, @args) = @_;
+    local($pid) = open(FH, "-|");
+    return undef unless defined($pid);
+    if ($pid == 0) {
+    exec $prog, @args;
+    &mydie("exec $prog failed\n");
+    }
+    1;
+}
+
+# CGI script must die with error status 0
+sub mydie {
+	local($message) = @_;
+	print &html_header("Error");
+	print $message;
+
+print qq{
+
+Index Page and Help
+
+
+};
+
+	exit(0);
+}
diff --git a/doc/notify-dns-slaves.1 b/doc/notify-dns-slaves.1
new file mode 100644
index 0000000..4ee4d55
--- /dev/null
+++ b/doc/notify-dns-slaves.1
@@ -0,0 +1,86 @@
+.\" 
+.\" 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 
+.\"
+.Dd June, 2008
+.Dt notify-dns-slaves
+.Os slapi-dnsnotify 
+.Sh NAME
+.Nm notify-dns-slaves
+.Nd is a tool which can notify DNS slaves to update their copy of 
+a DNS zone. 
+.Sh SYNOPSIS
+.Nm
+.Fl s 
+.Op Fl w Ar wait
+.Op Fl d Ar level
+.Nm
+.Op Fl d Ar level
+zone server ...
+.Sh DESCRIPTION
+.Nm 
+is used by the  
+.Xr slapi-dnsnotify 8
+LDAP plugin to send out notifications that DNS zones have been updated.
+.Pp
+It can also be used directly as a tool. The zone to send notifications about, 
+and servers to notify are specified on the command line. 
+.Pp
+When used with the 
+.Fl s
+option the tool goes into 'slave' mode. It remains running it expects specially 
+formatted requests on stdin. When in 'slave' mode, logging goes to syslog under
+the 
+.Em daemon 
+facility.  
+.Sh OPTIONS
+.Bl -tag -width Fl
+.It Fl d Ar level 
+Specifies what level of messages to display. 0 has only errors
+and warnings, with 4 being the most verbose.
+.It Fl s
+Work in 'slave' mode. Requests are expected on stdin. Used by the 
+.Xr slapi-dnsnotify 8
+plugin to send out notifications. 
+.It Fl w Ar wait
+When in 'slave' mode, the number of seconds to wait before sending
+out DNS notifications. This is usually controlled with the 
+.Em notify-delay
+option to 
+.Xr slapi-dnsnotify 8
+.Sh SEE ALSO
+.Xr slapi-dnsnotify 8
+.Sh AUTHOR
+.An Stef Walter Aq stef@memberwebs.com
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 
+.\"
+.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
-- 
cgit v1.2.3