initial1.0.0

28 files changed, 3023 insertions, 0 deletions

diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..d7f7486
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,51 @@
+NAME=pingdomfetch
+all: version documentation perltidy
+version:
+	cut -d' ' -f2 debian/changelog | head -n 1 | sed 's/(//;s/)//' > .version
+perltidy:
+	find . -name \*.pm | xargs perltidy -b
+	perltidy -b $(NAME)
+	find . -name \*.bak -delete
+documentation:
+	pod2man --release="$(NAME) $$(cat .version)" \
+                       --center="User Commands" ./docs/$(NAME).pod > ./docs/$(NAME).1
+	pod2text ./docs/$(NAME).pod > ./docs/$(NAME).txt
+	cp ./docs/${NAME}.pod ./README.pod
+install:
+	test ! -d $(DESTDIR)/usr/bin && mkdir -p $(DESTDIR)/usr/bin || exit 0
+	test ! -d $(DESTDIR)/var/run/pingdomfetch && mkdir -p $(DESTDIR)/var/run/pingdomfetch || exit 0
+	test ! -d $(DESTDIR)/usr/share/$(NAME)/examples && mkdir -p $(DESTDIR)/usr/share/$(NAME)/examples || exit 0
+	cp $(NAME) $(DESTDIR)/usr/bin
+	cp -r ./lib $(DESTDIR)/usr/share/$(NAME)/lib
+	cp ./.version $(DESTDIR)/usr/share/$(NAME)/version
+	cp ./pingdomfetch.conf.sample $(DESTDIR)/usr/share/$(NAME)/examples/pingdomfetch.conf.sample
+deinstall:
+	test ! -z "$(DESTDIR)" && test -f $(DESTDIR)/usr/bin/$(NAME) && rm $(DESTDIR)/usr/bin/$(NAME) || exit 0
+	test ! -z "$(DESTDIR)/usr/share/$(NAME)" && -d $(DESTDIR)/usr/share/$(NAME) && rm -r $(DESTDIR)/usr/share/$(NAME) || exit 0
+clean:
+	test -d $(DESTDIR) && rm -Rf $(DESTDIR)
+dch:
+	dch -i
+deb: 
+	dpkg-buildpackage -uc -us
+dput: deb
+	bash -c "dput -u incoming-debrepo ../$(NAME)_$$(cat ./debian/pingdomfetch/usr/share/pingdomfetch/version)_amd64.changes"
+release: all dch deb dput 
+	git commit -a -m 'New release'
+	bash -c "git tag $$(cat ./debian/pingdomfetch/usr/share/pingdomfetch/version)"
+	git push origin master
+	git push --tags
+clean-top:
+	rm ../$(NAME)_*.tar.gz
+	rm ../$(NAME)_*.dsc
+	rm ../$(NAME)_*.changes
+	rm ../$(NAME)_*.deb
+tmp-top:
+	mv ../$(NAME)_*.tar.gz /tmp
+	mv ../$(NAME)_*.dsc /tmp
+	mv ../$(NAME)_*.changes /tmp
+	mv ../$(NAME)_*.deb /tmp
+testrun:
+	./pingdomfetch --all-tls --config pingdomfetch.conf.test 
+testrun_verbose:
+	./pingdomfetch --all-tls --config pingdomfetch.conf.test --verbose
diff --git a/README.pod b/README.pod
new file mode 100644
index 0000000..42e49db
--- /dev/null
+++ b/README.pod
@@ -0,0 +1,217 @@
+=head1 NAME
+
+pingdomfetch - A small and humble tool to fetch availability stats from Pingdom and notify via E-Mail
+
+=head1 SYNOPSIS
+
+pingdomfetch
+    [--all-services]
+    [--all-tls]
+    [--checkid <STRING>]
+    [--config <STRING>]
+    [--flatten <STRING>]
+    [--from <STRING>]
+    [--help]
+    [--list-services]
+    [--list-tls]
+    [--notify]
+    [--notify-dummy]
+    [--notify-info]
+    [--service <STRING>]
+    [--sort-reverse]
+    [--tls <STRING>]
+    [--to <STRING>]
+    [--verbose]
+    [--version]
+
+
+=head1 DESCRIPTION
+
+pingdomfetch is a tool to fetch availability stats from www.Pingdom.com and notifies the results via Email. You may use this script to extend it to do other things with the results as well. Pingdom already provides notification emailing.
+
+Pingdomfetch also knows about 'so called' top level services (one top level service consists of several services).
+
+=head1 CONFIG
+
+=head2 Possible locations
+
+Create a config at one of the following (or into several) location:
+
+    /etc/pingdomfetch.conf
+    ./pingdomfetch.conf
+    /etc/pingdomfetch.d/*.conf
+    ~/.pingdomfetch.conf
+    ~/.pingdomfetch.d/*.conf
+
+The last config file always overwrites the values configured in the previous config files. For this use the sample configuration file F</usr/share/pingdomfetch/examples/pingdomfetch.conf.sample>. Please read that sample configuration file carefully since it also describes all available config options.
+
+It makes sense to have one global config F</etc/pingdomfetch.conf> containing all general configurations and for each top level service a separate config in F</etc/pingdomfetch.d/TLSNAME.conf>.
+
+=head2 Top level services and services
+
+=head3 Configure a top level service:
+
+Each top level service consists of many services. Since Pingdom does not know about top level services but just about separate checks (which are separate services) pingdomfetch fetches the availability of all services and calculates an average availability of all services which belong to a top level service.
+
+For each top level service you monitor via Pingdom you must create checks at Pingdom (manually). The check names should be of the form of 
+
+    PROCOCOL://FQDN
+
+For example:
+
+    http://paul.buetow.org
+
+    https://paul.buetow.org
+
+just in order to have it uniform to all the other Pingdom checks (there is no technical reason though).
+
+Afterwards create a new file F</etc/pingdomfetch.d/TLSNAME.conf> (for example F</etc/pingdomfetch.d/buetoworg_tls.conf>) with the following content:
+
+    [tls.TLSNAME]
+    PROCOCOL1://FQDN1
+    PROCOCOL2://FQDN2
+
+to be specific it should be like this:
+
+    [tls.buetoworg_paul]
+    http://paul.buetow.org
+    https://paul.buetow.org
+
+The buetoworg_tls will be used by pingdomfetch to identify the top level service (e.g. using --list-tls) and can be freely chosen. 
+
+=head3 Fetch stats of the top level service:
+
+The command
+
+    pingdomfetch --tls buetoworg_tls
+
+fetches the availability of both services from Pingdom and calculates the average availability which is the tls availability and prints out the results to stdout.
+
+    pingdomfetch --from yesterday --to yesterday --flatten bod:eod --all-tls 
+
+fetches the availability of yesteday of all configured tls. There are many other options available. 
+
+=head3 Service options
+
+It is possible to configure special options for special services:
+
+    [tls.TLSNAME]
+    PROCOCOL1://FQDN1[=option1:value1[,option2:value2]
+    PROCOCOL2://FQDN2[=option1:value1[,option2:value2]
+
+The possible options are:
+
+=over
+
+=item weight
+
+If FQDN1 has twice as much traffic as FQDN2 it makes sense to increase its weight. The standard weight is 1. Its used to calculate the tls availability.
+
+=item warning
+
+This overwrites the global warning threshold. It makes sense to use to avoid staus mails just because one specific service is under the specified global warning threshold.
+
+=back
+
+to be specific it should be like this:
+
+    [tls.buetoworg_tls.4352844]
+    http://paul.buetow.org=weight:2,warning:98
+    https://paul.buetow.org=warning:100
+
+and means that the availability of plain http will count twice as much as much. A warning mail will be sent only if the availability is less than 98% for http or less than 100% for https.
+
+=head1 PINGDOMFETCH OPTIONS
+
+=over
+
+=item --all-services
+
+Fetch availability of all services.
+
+=item --all-tls
+
+Fetch availability of all top level services
+
+=item --checkid <NUMBER>
+
+Fetch availability of a specific check ID. The check ID is the Pingdom check ID.
+
+=item --config <STRING>
+
+Also read a specific config file.
+
+=item --flatten <STRING>
+
+Flatten the time interval to fetch availabilities for. E.g.:
+
+    --from yesterday --to yesterday --flatten bod:eod
+
+fetches the availability from begin of day (yesterday) until the end of the day (yesterday).
+
+=item --from <STRING>
+
+Set time interval start time to fetch availabilities for. All formats supported by Time::ParseDate can be used. See L<http://search.cpan.org/~muir/Time-modules-2003.0211/lib/Time/ParseDate.pm>.
+
+For example:
+    
+    --from today
+
+    --from '03.02.2013 12:34:56'
+
+    --from 'last week'
+
+=item --help
+
+Print out a brief help.
+
+=item --list-services
+
+List all configured services.
+
+=item --list-tls
+
+List all configured top level services.
+
+=item --notify
+
+Write a mail to all addresses specified in notify.email.to if at least one service or top level service is in state warning or critical. The warning threshold in % is warning.if.avail.is.less, the critical threshold in % is critical.if.avail.is.less.
+
+=item --notify-dummy
+
+In conjunction with --notify or --notify-info don't actually send mails but print them to stdout.
+
+=item --notify-info
+
+Write a mail to all addresses specified in notify.info.mail.to regardless of warning and critical services and top level services.
+
+=item --service <STRING>
+
+Fetch availability of a specific service name. The service name can be taken from --list-services.
+
+=item --sort-reverse
+
+Reverse the availability output list. Affects only status mails and stdout.
+
+=item --tls <STRING>
+
+Fetch availability of a specific top level service. The top level service name can be taken from --list-tls.
+
+=item --to <STRING>
+
+Same as --from, but specifies the end time to fetch availabilities for.
+
+=item --verbose
+
+Turns on verbose mode. Enables some extra output to stdout.
+
+=item --version
+
+Prints out the current version of pingdomfetch.
+
+=back
+
+=head1 AUTHOR
+
+Paul Buetow - <paul@buetow.org>
+
diff --git a/debian/README b/debian/README
new file mode 100644
index 0000000..e741a32
--- /dev/null
+++ b/debian/README
@@ -0,0 +1,7 @@
+The Debian Package pingdomfetch
+----------------------------
+
+This is just a hobby project. Not sure if everything meets the debian 
+policy though.
+
+ -- Paul Buetow <paul@buetow.org>  Sun, 08 Apr 2012 15:23:53 +0200
diff --git a/debian/changelog b/debian/changelog
new file mode 100644
index 0000000..7dfa797
--- /dev/null
+++ b/debian/changelog
@@ -0,0 +1,5 @@
+pingdomfetch (1.0.0) wheezy; urgency=low
+
+  * Initial release
+
+ -- Paul Buetow <paul@buetow.org>  Thu, 11 Dec 2014 16:24:50 +0100
diff --git a/debian/compat b/debian/compat
new file mode 100644
index 0000000..45a4fb7
--- /dev/null
+++ b/debian/compat
@@ -0,0 +1 @@
+8
diff --git a/debian/control b/debian/control
new file mode 100644
index 0000000..8a71a22
--- /dev/null
+++ b/debian/control
@@ -0,0 +1,15 @@
+Source: pingdomfetch
+Section: utils
+Priority: optional
+Maintainer: Paul Buetow <paul@buetoe.org
+Build-Depends: perl, perltidy
+Standards-Version: 3.9.2
+Homepage: http://pingdomfetch.buetow.org
+Vcs-Git: https://github.com/ratnanplan/pingdomfetch
+Vcs-Browser: https://github.com/rantanplan/pingdomfetch
+
+Package: pingdomfetch
+Architecture: all
+Depends: ${perl:Depends}, libwww-perl, libtime-modules-perl, libconfig-json-perl, libio-socket-ssl-perl, libmime-lite-perl, curl, libio-captureoutput-perl
+Description: Pingdom fetch utility
+ Fetches service availability from Pingdom and notifies via E-Mail
diff --git a/debian/copyright b/debian/copyright
new file mode 100644
index 0000000..9353cd5
--- /dev/null
+++ b/debian/copyright
@@ -0,0 +1,30 @@
+Format: http://dep.debian.net/deps/dep5
+Upstream-Name: pingdomfetch
+Source: http://pingdomfetch.buetow.org
+
+Files: *
+Copyright: 2012 Paul Buetow <paul@buetow.org>
+License: GPL-3.0+
+
+Files: debian/*
+Copyright: 2012 Paul Buetow <paul@buetow.org>
+License: GPL-3.0+
+
+License: GPL-3.0+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+ .
+ This package is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+ .
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see <http://www.gnu.org/licenses/>.
+ .
+ On Debian systems, the complete text of the GNU General
+ Public License version 3 can be found in "/usr/share/common-licenses/GPL-3".
+
+
diff --git a/debian/files b/debian/files
new file mode 100644
index 0000000..6625ca6
--- /dev/null
+++ b/debian/files
@@ -0,0 +1 @@
+pingdomfetch_1.0.0_all.deb utils optional
diff --git a/debian/pingdomfetch.debhelper.log b/debian/pingdomfetch.debhelper.log
new file mode 100644
index 0000000..545a50f
--- /dev/null
+++ b/debian/pingdomfetch.debhelper.log
@@ -0,0 +1,45 @@
+dh_auto_configure
+dh_auto_build
+dh_auto_test
+dh_prep
+dh_installdirs
+dh_auto_install
+dh_install
+dh_installdocs
+dh_installchangelogs
+dh_installexamples
+dh_installman
+dh_installcatalogs
+dh_installcron
+dh_installdebconf
+dh_installemacsen
+dh_installifupdown
+dh_installinfo
+dh_pysupport
+dh_installinit
+dh_installmenu
+dh_installmime
+dh_installmodules
+dh_installlogcheck
+dh_installlogrotate
+dh_installpam
+dh_installppp
+dh_installudev
+dh_installwm
+dh_installxfonts
+dh_installgsettings
+dh_bugfiles
+dh_ucf
+dh_lintian
+dh_gconf
+dh_icons
+dh_perl
+dh_usrlocal
+dh_link
+dh_compress
+dh_fixperms
+dh_installdeb
+dh_gencontrol
+dh_md5sums
+dh_builddeb
+dh_builddeb
diff --git a/debian/pingdomfetch.manpages b/debian/pingdomfetch.manpages
new file mode 100644
index 0000000..f52d634
--- /dev/null
+++ b/debian/pingdomfetch.manpages
@@ -0,0 +1 @@
+docs/pingdomfetch.1
diff --git a/debian/pingdomfetch.substvars b/debian/pingdomfetch.substvars
new file mode 100644
index 0000000..bcb0957
--- /dev/null
+++ b/debian/pingdomfetch.substvars
@@ -0,0 +1,2 @@
+perl:Depends=perl
+misc:Depends=
diff --git a/debian/rules b/debian/rules
new file mode 100755
index 0000000..b760bee
--- /dev/null
+++ b/debian/rules
@@ -0,0 +1,13 @@
+#!/usr/bin/make -f
+# -*- makefile -*-
+# Sample debian/rules that uses debhelper.
+# This file was originally written by Joey Hess and Craig Small.
+# As a special exception, when this file is copied by dh-make into a
+# dh-make output file, you may use that output file without restriction.
+# This special exception was added by Craig Small in version 0.37 of dh-make.
+
+# Uncomment this to turn on verbose mode.
+#export DH_VERBOSE=1
+
+%:
+	dh $@ 
diff --git a/debian/source/format b/debian/source/format
new file mode 100644
index 0000000..89ae9db
--- /dev/null
+++ b/debian/source/format
@@ -0,0 +1 @@
+3.0 (native)
diff --git a/docs/pingdomfetch.1 b/docs/pingdomfetch.1
new file mode 100644
index 0000000..fad010e
--- /dev/null
+++ b/docs/pingdomfetch.1
@@ -0,0 +1,337 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "PINGDOMFETCH 1"
+.TH PINGDOMFETCH 1 "2015-01-02" "pingdomfetch " "User Commands"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+pingdomfetch \- A small and humble tool to fetch availability stats from Pingdom and notify via E\-Mail
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+pingdomfetch
+    [\-\-all\-services]
+    [\-\-all\-tls]
+    [\-\-checkid <\s-1STRING\s0>]
+    [\-\-config <\s-1STRING\s0>]
+    [\-\-flatten <\s-1STRING\s0>]
+    [\-\-from <\s-1STRING\s0>]
+    [\-\-help]
+    [\-\-list\-services]
+    [\-\-list\-tls]
+    [\-\-notify]
+    [\-\-notify\-dummy]
+    [\-\-notify\-info]
+    [\-\-service <\s-1STRING\s0>]
+    [\-\-sort\-reverse]
+    [\-\-tls <\s-1STRING\s0>]
+    [\-\-to <\s-1STRING\s0>]
+    [\-\-verbose]
+    [\-\-version]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+pingdomfetch is a tool to fetch availability stats from www.Pingdom.com and notifies the results via Email. You may use this script to extend it to do other things with the results as well. Pingdom already provides notification emailing.
+.PP
+Pingdomfetch also knows about 'so called' top level services (one top level service consists of several services).
+.SH "CONFIG"
+.IX Header "CONFIG"
+.SS "Possible locations"
+.IX Subsection "Possible locations"
+Create a config at one of the following (or into several) location:
+.PP
+.Vb 5
+\&    /etc/pingdomfetch.conf
+\&    ./pingdomfetch.conf
+\&    /etc/pingdomfetch.d/*.conf
+\&    ~/.pingdomfetch.conf
+\&    ~/.pingdomfetch.d/*.conf
+.Ve
+.PP
+The last config file always overwrites the values configured in the previous config files. For this use the sample configuration file \fI/usr/share/pingdomfetch/examples/pingdomfetch.conf.sample\fR. Please read that sample configuration file carefully since it also describes all available config options.
+.PP
+It makes sense to have one global config \fI/etc/pingdomfetch.conf\fR containing all general configurations and for each top level service a separate config in \fI/etc/pingdomfetch.d/TLSNAME.conf\fR.
+.SS "Top level services and services"
+.IX Subsection "Top level services and services"
+\fIConfigure a top level service:\fR
+.IX Subsection "Configure a top level service:"
+.PP
+Each top level service consists of many services. Since Pingdom does not know about top level services but just about separate checks (which are separate services) pingdomfetch fetches the availability of all services and calculates an average availability of all services which belong to a top level service.
+.PP
+For each top level service you monitor via Pingdom you must create checks at Pingdom (manually). The check names should be of the form of
+.PP
+.Vb 1
+\&    PROCOCOL://FQDN
+.Ve
+.PP
+For example:
+.PP
+.Vb 1
+\&    http://paul.buetow.org
+\&
+\&    https://paul.buetow.org
+.Ve
+.PP
+just in order to have it uniform to all the other Pingdom checks (there is no technical reason though).
+.PP
+Afterwards create a new file \fI/etc/pingdomfetch.d/TLSNAME.conf\fR (for example \fI/etc/pingdomfetch.d/buetoworg_tls.conf\fR) with the following content:
+.PP
+.Vb 3
+\&    [tls.TLSNAME]
+\&    PROCOCOL1://FQDN1
+\&    PROCOCOL2://FQDN2
+.Ve
+.PP
+to be specific it should be like this:
+.PP
+.Vb 3
+\&    [tls.buetoworg_paul]
+\&    http://paul.buetow.org
+\&    https://paul.buetow.org
+.Ve
+.PP
+The buetoworg_tls will be used by pingdomfetch to identify the top level service (e.g. using \-\-list\-tls) and can be freely chosen.
+.PP
+\fIFetch stats of the top level service:\fR
+.IX Subsection "Fetch stats of the top level service:"
+.PP
+The command
+.PP
+.Vb 1
+\&    pingdomfetch \-\-tls buetoworg_tls
+.Ve
+.PP
+fetches the availability of both services from Pingdom and calculates the average availability which is the tls availability and prints out the results to stdout.
+.PP
+.Vb 1
+\&    pingdomfetch \-\-from yesterday \-\-to yesterday \-\-flatten bod:eod \-\-all\-tls
+.Ve
+.PP
+fetches the availability of yesteday of all configured tls. There are many other options available.
+.PP
+\fIService options\fR
+.IX Subsection "Service options"
+.PP
+It is possible to configure special options for special services:
+.PP
+.Vb 3
+\&    [tls.TLSNAME]
+\&    PROCOCOL1://FQDN1[=option1:value1[,option2:value2]
+\&    PROCOCOL2://FQDN2[=option1:value1[,option2:value2]
+.Ve
+.PP
+The possible options are:
+.IP "weight" 4
+.IX Item "weight"
+If \s-1FQDN1\s0 has twice as much traffic as \s-1FQDN2\s0 it makes sense to increase its weight. The standard weight is 1. Its used to calculate the tls availability.
+.IP "warning" 4
+.IX Item "warning"
+This overwrites the global warning threshold. It makes sense to use to avoid staus mails just because one specific service is under the specified global warning threshold.
+.PP
+to be specific it should be like this:
+.PP
+.Vb 3
+\&    [tls.buetoworg_tls.4352844]
+\&    http://paul.buetow.org=weight:2,warning:98
+\&    https://paul.buetow.org=warning:100
+.Ve
+.PP
+and means that the availability of plain http will count twice as much as much. A warning mail will be sent only if the availability is less than 98% for http or less than 100% for https.
+.SH "PINGDOMFETCH OPTIONS"
+.IX Header "PINGDOMFETCH OPTIONS"
+.IP "\-\-all\-services" 4
+.IX Item "--all-services"
+Fetch availability of all services.
+.IP "\-\-all\-tls" 4
+.IX Item "--all-tls"
+Fetch availability of all top level services
+.IP "\-\-checkid <\s-1NUMBER\s0>" 4
+.IX Item "--checkid <NUMBER>"
+Fetch availability of a specific check \s-1ID\s0. The check \s-1ID\s0 is the Pingdom check \s-1ID\s0.
+.IP "\-\-config <\s-1STRING\s0>" 4
+.IX Item "--config <STRING>"
+Also read a specific config file.
+.IP "\-\-flatten <\s-1STRING\s0>" 4
+.IX Item "--flatten <STRING>"
+Flatten the time interval to fetch availabilities for. E.g.:
+.Sp
+.Vb 1
+\&    \-\-from yesterday \-\-to yesterday \-\-flatten bod:eod
+.Ve
+.Sp
+fetches the availability from begin of day (yesterday) until the end of the day (yesterday).
+.IP "\-\-from <\s-1STRING\s0>" 4
+.IX Item "--from <STRING>"
+Set time interval start time to fetch availabilities for. All formats supported by Time::ParseDate can be used. See http://search.cpan.org/~muir/Time\-modules\-2003.0211/lib/Time/ParseDate.pm <http://search.cpan.org/~muir/Time-modules-2003.0211/lib/Time/ParseDate.pm>.
+.Sp
+For example:
+.Sp
+.Vb 1
+\&    \-\-from today
+\&
+\&    \-\-from \*(Aq03.02.2013 12:34:56\*(Aq
+\&
+\&    \-\-from \*(Aqlast week\*(Aq
+.Ve
+.IP "\-\-help" 4
+.IX Item "--help"
+Print out a brief help.
+.IP "\-\-list\-services" 4
+.IX Item "--list-services"
+List all configured services.
+.IP "\-\-list\-tls" 4
+.IX Item "--list-tls"
+List all configured top level services.
+.IP "\-\-notify" 4
+.IX Item "--notify"
+Write a mail to all addresses specified in notify.email.to if at least one service or top level service is in state warning or critical. The warning threshold in % is warning.if.avail.is.less, the critical threshold in % is critical.if.avail.is.less.
+.IP "\-\-notify\-dummy" 4
+.IX Item "--notify-dummy"
+In conjunction with \-\-notify or \-\-notify\-info don't actually send mails but print them to stdout.
+.IP "\-\-notify\-info" 4
+.IX Item "--notify-info"
+Write a mail to all addresses specified in notify.info.mail.to regardless of warning and critical services and top level services.
+.IP "\-\-service <\s-1STRING\s0>" 4
+.IX Item "--service <STRING>"
+Fetch availability of a specific service name. The service name can be taken from \-\-list\-services.
+.IP "\-\-sort\-reverse" 4
+.IX Item "--sort-reverse"
+Reverse the availability output list. Affects only status mails and stdout.
+.IP "\-\-tls <\s-1STRING\s0>" 4
+.IX Item "--tls <STRING>"
+Fetch availability of a specific top level service. The top level service name can be taken from \-\-list\-tls.
+.IP "\-\-to <\s-1STRING\s0>" 4
+.IX Item "--to <STRING>"
+Same as \-\-from, but specifies the end time to fetch availabilities for.
+.IP "\-\-verbose" 4
+.IX Item "--verbose"
+Turns on verbose mode. Enables some extra output to stdout.
+.IP "\-\-version" 4
+.IX Item "--version"
+Prints out the current version of pingdomfetch.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Paul Buetow \- <paul@buetow.org>
diff --git a/docs/pingdomfetch.pod b/docs/pingdomfetch.pod
new file mode 100644
index 0000000..42e49db
--- /dev/null
+++ b/docs/pingdomfetch.pod
@@ -0,0 +1,217 @@
+=head1 NAME
+
+pingdomfetch - A small and humble tool to fetch availability stats from Pingdom and notify via E-Mail
+
+=head1 SYNOPSIS
+
+pingdomfetch
+    [--all-services]
+    [--all-tls]
+    [--checkid <STRING>]
+    [--config <STRING>]
+    [--flatten <STRING>]
+    [--from <STRING>]
+    [--help]
+    [--list-services]
+    [--list-tls]
+    [--notify]
+    [--notify-dummy]
+    [--notify-info]
+    [--service <STRING>]
+    [--sort-reverse]
+    [--tls <STRING>]
+    [--to <STRING>]
+    [--verbose]
+    [--version]
+
+
+=head1 DESCRIPTION
+
+pingdomfetch is a tool to fetch availability stats from www.Pingdom.com and notifies the results via Email. You may use this script to extend it to do other things with the results as well. Pingdom already provides notification emailing.
+
+Pingdomfetch also knows about 'so called' top level services (one top level service consists of several services).
+
+=head1 CONFIG
+
+=head2 Possible locations
+
+Create a config at one of the following (or into several) location:
+
+    /etc/pingdomfetch.conf
+    ./pingdomfetch.conf
+    /etc/pingdomfetch.d/*.conf
+    ~/.pingdomfetch.conf
+    ~/.pingdomfetch.d/*.conf
+
+The last config file always overwrites the values configured in the previous config files. For this use the sample configuration file F</usr/share/pingdomfetch/examples/pingdomfetch.conf.sample>. Please read that sample configuration file carefully since it also describes all available config options.
+
+It makes sense to have one global config F</etc/pingdomfetch.conf> containing all general configurations and for each top level service a separate config in F</etc/pingdomfetch.d/TLSNAME.conf>.
+
+=head2 Top level services and services
+
+=head3 Configure a top level service:
+
+Each top level service consists of many services. Since Pingdom does not know about top level services but just about separate checks (which are separate services) pingdomfetch fetches the availability of all services and calculates an average availability of all services which belong to a top level service.
+
+For each top level service you monitor via Pingdom you must create checks at Pingdom (manually). The check names should be of the form of 
+
+    PROCOCOL://FQDN
+
+For example:
+
+    http://paul.buetow.org
+
+    https://paul.buetow.org
+
+just in order to have it uniform to all the other Pingdom checks (there is no technical reason though).
+
+Afterwards create a new file F</etc/pingdomfetch.d/TLSNAME.conf> (for example F</etc/pingdomfetch.d/buetoworg_tls.conf>) with the following content: