[postfwd] 66/96: restructure documentation
Jan Wagner
waja at alioth.debian.org
Tue Nov 5 20:09:44 UTC 2013
This is an automated email from the git hooks/post-receive script.
waja pushed a commit to branch master
in repository postfwd.
commit 75ad0273c043365f1dfec79e64fb744c4e8abeb4
Author: Jan Wagner <waja at cyconet.org>
Date: Wed Sep 14 12:56:18 2011 +0000
restructure documentation
---
debian/changelog | 4 +
debian/patches/00list | 1 +
debian/patches/10_hapolicy_manpage.dpatch | 177 +++++++++++++++++++++++++++++
debian/postfwd.docs | 12 +-
debian/postfwd.manpages | 3 +
debian/rules | 8 +-
6 files changed, 198 insertions(+), 7 deletions(-)
diff --git a/debian/changelog b/debian/changelog
index 7767634..719f363 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -13,6 +13,10 @@ postfwd (1.30-1) UNRELEASED; urgency=low
- documentation updates and fixes
* Suppress output on restarting via init script (Closes: #636782), thanks
Martin F. Krafft for reporting
+ * Reorganize documentation
+ - Add new files from upstream to documentation
+ - Add 10_hapolicy_manpage.dpatch to have a manpage for hapolicy
+ - Changelogs where renamed by upstream
-- Jan Wagner <waja at cyconet.org> Thu, 10 Feb 2011 08:40:51 +0100
diff --git a/debian/patches/00list b/debian/patches/00list
index e69de29..5708b67 100644
--- a/debian/patches/00list
+++ b/debian/patches/00list
@@ -0,0 +1 @@
+10_hapolicy_manpage.dpatch
diff --git a/debian/patches/10_hapolicy_manpage.dpatch b/debian/patches/10_hapolicy_manpage.dpatch
new file mode 100755
index 0000000..6bcfdbb
--- /dev/null
+++ b/debian/patches/10_hapolicy_manpage.dpatch
@@ -0,0 +1,177 @@
+#! /bin/sh /usr/share/dpatch/dpatch-run
+## 10_hapolicy_manpage.dpatch by Jan Wagner <waja at cyconet.org>
+##
+## DP: Add manpage for hapolicy
+
+ at DPATCH@
+diff -urNad '--exclude=CVS' '--exclude=.svn' '--exclude=.git' '--exclude=.arch' '--exclude=.hg' '--exclude=_darcs' '--exclude=.bzr' postfwd-1.30~/man/man8/hapolicy.1 postfwd-1.30/man/man8/hapolicy.1
+--- postfwd-1.30~/man/man8/hapolicy.1 1970-01-01 01:00:00.000000000 +0100
++++ postfwd-1.30/man/man8/hapolicy.1 2011-09-14 14:45:34.000000000 +0200
+@@ -0,0 +1,155 @@
++.\"Text automatically generated by txt2man
++.TH HAPOLICY 1 "2011-09-14" "" ""
++.SH NAME
++\fBhapolicy \fP- policy delegation high availability script
++\fB
++.SH SYNOPSIS
++.nf
++.fam C
++ \fBhapolicy\fP [\fIOPTIONS\fP] \fB--service\fP=SERVICE1 [\fB--service\fP=SERVICE2 \.\.\.]
++
++.nf
++.fam C
++ Services:
++ \fB-s\fP, \fB--service\fP <name>=<address>:<port>[:<prio>:<weight>:<timeout>]
++
++ Options:
++ \fB-d\fP, \fB--default\fP <action> \fIreturns\fP <action> \fIif\fP \fIno\fP \fIservice\fP \fIwas\fP \fIavailable\fP [default: 'dunno']
++ \fB-l\fP, \fB--logging\fP \fIlog\fP \fIrequests\fP
++ \fB-v\fP, \fB--verbose\fP \fIincrease\fP \fIlogging\fP \fIverbosity\fP
++ \fB-L\fP, \fB--stdout\fP \fIlog\fP \fIto\fP stdout, \fIfor\fP debugging, \fIdo\fP \fINOT\fP \fIuse\fP \fIwith\fP \fIpostfix\fP
++
++.fam T
++.fi
++.fam T
++.fi
++.SH DESCRIPTION
++.SS INTRODUCTION
++\fBhapolicy\fP enables high availability, weighted loadbalancing and a
++fallback action \fIfor\fP \fIpostfix\fP policy delegation services. Invoked via
++\fIpostfix\fP spawn it acts as a wrapper that queries other policy servers via
++tcp connection. The order of the \fIservice\fP queries can be influenced by
++assigning a specific priority and weight \fIto\fP each \fIservice\fP. A \fIservice\fP is
++considered 'failing', \fIif\fP the connection is refused or the specified
++\fIservice\fP timeout is reached. If all of the configured policy services
++were failing, \fBhapolicy\fP \fIreturns\fP a default action (e.g. dunno) \fIto\fP \fIpostfix\fP.
++.PP
++With version 1.00 \fBhapolicy\fP has less than 200 lines of perl code using
++only standard perl modules. It does not require any disk access nor
++configuration files and runs under an unpriviledged user account. This
++should allow fast and reliable operation.
++.SS CONFIGURATION
++A \fIservice\fP has the following attributes
++.PP
++.nf
++.fam C
++ "servicename" => {
++ ip => '127.0.0.1', # ip address
++ port => '10040', # tcp port
++ prio => '10', # optional, lower wins
++ weight => '1', # optional, for items with same prio (weighted round-robin), higher is better
++ timeout => '30', # optional, query timeout in seconds
++ },
++
++.fam T
++.fi
++You may define multiple services at the command line. Which means that
++.PP
++.nf
++.fam C
++ hapolicy -s "grey1=10.0.0.1:10031:10" -s "grey2=10.0.0.2:10031:20"
++
++.fam T
++.fi
++will always try first \fIservice\fP *grey1* at ip 10.0.0.1 port 10031 and \fIif\fP
++that \fIservice\fP is not \fIavailable\fP or does not answer within the default of
++30 seconds the next \fIservice\fP *grey2* at ip 10.0.0.2 port 10031 will be
++queried.
++.PP
++If you want \fIto\fP load balance connections you may define
++.PP
++.nf
++.fam C
++ hapolicy -s "polw1=10.0.0.1:12525:10:2" -s "polw2=10.0.0.2:12525:10:1"
++
++.fam T
++.fi
++which queries \fIservice\fP *polw1* at ip 10.0.0.1 twice as much as \fIservice\fP
++*polw2* at ip 10.0.0.2. Note that this setup also ensures high
++availability \fIfor\fP both services. If *polw1* is not \fIavailable\fP or does not
++answer within the default of 30 seconds *polw2* will be queried and vice
++versa. There is \fIno\fP reason \fIto\fP define a \fIservice\fP twice.
++.SS INTEGRATION
++Enter the following at the bottom of your \fIpostfix\fP master.cf (usually
++located at /etc/\fIpostfix\fP):
++.PP
++.nf
++.fam C
++ # service description, note the leading blanks at the second line
++ 127.0.0.1:10060 inet n n n - 0 spawn
++ user=nobody argv=/usr/local/bin/hapolicy -l -s GREY1=10.0.0.1:10031:10 -s GREY2=10.0.0.2:10031:10
++
++.fam T
++.fi
++save the file and open \fIpostfix\fP main.cf. Modify it as follows:
++.PP
++.nf
++.fam C
++ 127.0.0.1:10060_time_limit = 3600
++
++ smtpd_recipient_restrictions =
++ permit_mynetworks,
++ \.\.\. other authed permits \.\.\.
++ reject_unauth_destination,
++ \.\.\. other restrictions \.\.\.
++ check_policy_service inet:127.0.0.1:10060 # <- hapolicy query
++
++.fam T
++.fi
++Now issue '\fIpostfix\fP reload' at the command line. Of course you can have
++more enhanced setups using \fIpostfix\fP restriction classes. Please see
++"LINKS" \fIfor\fP further options.
++.SH LINKS
++[1] Postfix SMTP Access Policy Delegation
++<http://www.postfix.org/SMTPD_POLICY_README.html>
++.PP
++[2] Postfix Per-Client/User/etc. Access Control
++<http://www.postfix.org/RESTRICTION_CLASS_README.html>
++.SH LICENSE
++\fBhapolicy\fP is free software and released under BSD license, which
++basically means that you can \fIdo\fP what you want as long as you keep the
++copyright notice:
++.PP
++Copyright (c) 2008, Jan Peter Kessler All rights reserved.
++.PP
++Redistribution and \fIuse\fP in source and binary forms, \fIwith\fP or without
++modification, are permitted provided that the following conditions are
++met:
++.RS
++.IP \(bu 3
++Redistributions of source code must retain the above copyright
++notice, this list of conditions and the following disclaimer.
++.IP \(bu 3
++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 \fIwith\fP the
++distribution.
++.IP \(bu 3
++Neither the name of the authors nor the names of his contributors
++may be used \fIto\fP endorse or promote products derived from this
++software without specific prior written permission.
++.RE
++.PP
++THIS SOFTWARE IS PROVIDED BY ME ``AS IS'' AND ANY EXPRESS OR IMPLIED
++WARRANTIES, INCLUDING, BUT \fINOT\fP LIMITED TO, THE IMPLIED WARRANTIES OF
++MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
++NO EVENT SHALL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
++EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT \fINOT\fP 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.
++.SH AUTHOR
++Jan Peter Kessler <info (AT) postfwd (DOT) org>. Let me know, \fIif\fP you
++have any suggestions.
+diff -urNad '--exclude=CVS' '--exclude=.svn' '--exclude=.git' '--exclude=.arch' '--exclude=.hg' '--exclude=_darcs' '--exclude=.bzr' postfwd-1.30~/tools/hapolicy/hapolicy.txt postfwd-1.30/tools/hapolicy/hapolicy.txt
+--- postfwd-1.30~/tools/hapolicy/hapolicy.txt 2011-08-16 08:32:03.000000000 +0200
++++ postfwd-1.30/tools/hapolicy/hapolicy.txt 2011-09-14 14:43:43.000000000 +0200
+@@ -8,7 +8,7 @@
+ -s, --service <name>=<address>:<port>[:<prio>:<weight>:<timeout>]
+
+ Options:
+- -d, --default <action> returns <action> if no service was available (default: 'dunno')
++ -d, --default <action> returns <action> if no service was available [default: 'dunno']
+ -l, --logging log requests
+ -v, --verbose increase logging verbosity
+ -L, --stdout log to stdout, for debugging, do NOT use with postfix
diff --git a/debian/postfwd.docs b/debian/postfwd.docs
index 3bb7ccf..310cce4 100644
--- a/debian/postfwd.docs
+++ b/debian/postfwd.docs
@@ -1,3 +1,9 @@
-doc/postfwd.html
-doc/postfwd.txt
-doc/CHANGELOG2
+#doc/postfwd.html
+#doc/postfwd.txt
+doc/postfwd2.CHANGELOG
+doc/*.html
+doc/*.txt
+tools/hapolicy/hapolicy.*
+tools/*.pl
+tools/*.sample
+plugins/*.sample
diff --git a/debian/postfwd.manpages b/debian/postfwd.manpages
new file mode 100644
index 0000000..2c9c21f
--- /dev/null
+++ b/debian/postfwd.manpages
@@ -0,0 +1,3 @@
+debian/tmp/postfwd1.8
+man/man8/postfwd2.8
+man/man8/hapolicy.1
diff --git a/debian/rules b/debian/rules
index d61831f..c1f23e4 100755
--- a/debian/rules
+++ b/debian/rules
@@ -29,12 +29,12 @@ install: build
binary-indep: build install
dh_testdir
dh_testroot
- dh_installchangelogs doc/CHANGELOG
- dh_installdocs tools
+ dh_installchangelogs doc/postfwd.CHANGELOG
+ dh_installdocs -Xhapolicy
+ dh_installdocs tools/hapolicy/hapolicy[0-9a-zA-Z.]*
dh_installexamples etc/postfwd.cf.sample debian/example-cfg*
dh_installinit -- defaults 19 21
- dh_installman man/man8/postfwd2.8
- dh_installman debian/tmp/postfwd1.8
+ dh_installman
dh_compress
dh_fixperms
dh_perl
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/postfwd.git
More information about the Pkg-perl-cvs-commits
mailing list