diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 10 | ||||
| -rwxr-xr-x | doc/man2html.pl | 230 | ||||
| -rw-r--r-- | doc/notify-dns-slaves.1 | 86 | ||||
| -rw-r--r-- | doc/slapi-dnsnotify.8 | 143 |
4 files changed, 469 insertions, 0 deletions
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 "<H1>Man Page: ${title}</H1>"; + print "<PRE>\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(<MAN>) { + # remove tailing white space + if (/^\s+$/) { + next if $space; + $space = 1; + } else { + $space = 0; + } + + $_ = &encode_data($_); + if($enable_include_links && + m,(<B>)?\#include(</B>)?\s+(<B>)?\<\;(.*\.h)\>\;(</B>)?,) { + $match = $4; ($regexp = $match) =~ s/\./\\\./; + s,$regexp,\<A HREF=\"$BASE/usr/include/$match\"\>$match\</A\>,; + } + /^\s/ && # skip headers + s,((<[IB]>)?[\w\_\.\-]+\s*(</[IB]>)?\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]+)/<A HREF="mailto:$1">$1<\/A>/gi; + } + + # detect URLs in manpages + if (m%tp://%) { + s,((ftp|http)://[^\s<>\)]+),<A HREF="$1">$1</A>,gi; + } + + if (/^<B>\S+/ && m%^<B>([^<]+)%) { + $i = $1; $j = &encode_url($i); + s%^<B>([^<]+)</B>%<B>$i</B>%; + push(@sect, $1); + } + print; + } + close(MAN); + + print "<H6> [ <a href='./'>back</a> | <a href='../../'>home</a> ]</h6>"; + print "</BODY>\n"; + print "</HTML>\n"; + + # Sleep 0.35 seconds to avoid DoS attacs + select undef, undef, undef, 0.35; +} + +# encode unknown data for use in <TITLE>...</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]</TITLE> +<link rev="made" href="mailto:wosch\@FreeBSD.ORG"> +<META name="robots" content="nofollow"> +<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type"> +<link rel="stylesheet" type="text/css" href="/swalter/style.css"> +</HEAD> +<BODY BGCOLOR="#FFFFFF" TEXT="#000000">\n\n}; +} + +sub mlnk { + local($matched) = @_; + return qq{<U>$matched</U>}; +} + +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{ +<p> +<A HREF="$BASE">Index Page and Help</A> +</BODY> +</HTML> +}; + + 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 <stef@memberwebs.com> +.\" +.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 <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 |