restructure documentation
This commit is contained in:
parent
c67cf1bdeb
commit
75ad0273c0
4
debian/changelog
vendored
4
debian/changelog
vendored
|
|
@ -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@cyconet.org> Thu, 10 Feb 2011 08:40:51 +0100
|
||||
|
||||
|
|
|
|||
1
debian/patches/00list
vendored
1
debian/patches/00list
vendored
|
|
@ -0,0 +1 @@
|
|||
10_hapolicy_manpage.dpatch
|
||||
177
debian/patches/10_hapolicy_manpage.dpatch
vendored
Executable file
177
debian/patches/10_hapolicy_manpage.dpatch
vendored
Executable file
|
|
@ -0,0 +1,177 @@
|
|||
#! /bin/sh /usr/share/dpatch/dpatch-run
|
||||
## 10_hapolicy_manpage.dpatch by Jan Wagner <waja@cyconet.org>
|
||||
##
|
||||
## DP: Add manpage for hapolicy
|
||||
|
||||
@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
|
||||
12
debian/postfwd.docs
vendored
12
debian/postfwd.docs
vendored
|
|
@ -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
|
||||
|
|
|
|||
3
debian/postfwd.manpages
vendored
Normal file
3
debian/postfwd.manpages
vendored
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
debian/tmp/postfwd1.8
|
||||
man/man8/postfwd2.8
|
||||
man/man8/hapolicy.1
|
||||
8
debian/rules
vendored
8
debian/rules
vendored
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue