man: initial man pages

5 files changed, 226 insertions, 0 deletions

diff --git a/man/.gitignore b/man/.gitignore
new file mode 100644
index 0000000..dd5c122
--- /dev/null
+++ b/man/.gitignore
@@ -0,0 +1 @@
+*.[58]
diff --git a/man/Makefile b/man/Makefile
new file mode 100644
index 0000000..b08f2f1
--- /dev/null
+++ b/man/Makefile
@@ -0,0 +1,30 @@
+
+MANDIR ?= /usr/share/man
+MAN5PAGES = pingu.conf.5
+MAN8PAGES = pingu.8 pinguctl.8
+ALL_MANPAGES = $(MAN5PAGES) $(MAN8PAGES)
+
+DEFAULT_ADM_SOCKET ?= /var/run/pingu/pingu.ctl
+DEFAULT_PIDFILE ?= /var/run/pingu/pingu.pid
+DEFAULT_CONFIG ?= /etc/pingu/pingu.conf
+
+SED := sed
+SED_REPLACE = -e 's:@DEFAULT_ADM_SOCKET@:$(DEFAULT_ADM_SOCKET):g' \
+	-e 's:@DEFAULT_PIDFILE@:$(DEFAULT_PIDFILE):g' \
+	-e 's:@DEFAULT_CONFIG@:$(DEFAULT_CONFIG):g'
+
+mkman	= $(SED) $(SED_REPLACE) $(SED_EXTRA) $< > $@
+.SUFFIXES: .in
+
+.in:
+	$(mkman)
+
+all:	$(ALL_MANPAGES)
+
+clean:
+	rm -f $(ALL_MANPAGES)
+
+install: $(ALL_MANPAGES)
+	$(INSTALLDIR) $(DESTDIR)$(MANDIR)/man5 $(DESTDIR)$(MANDIR)/man8
+	$(INSTALL) $(addprefix $(src)/,$(MAN5PAGES)) $(DESTDIR)$(MANDIR)/man5
+	$(INSTALL) $(addprefix $(src)/,$(MAN8PAGES)) $(DESTDIR)$(MANDIR)/man8
diff --git a/man/pingu.8.in b/man/pingu.8.in
new file mode 100644
index 0000000..a37b0b6
--- /dev/null
+++ b/man/pingu.8.in
@@ -0,0 +1,60 @@
+.Dd October 14, 2011
+.Dt PINGU 8 Linux
+.Os
+
+.Sh NAME
+.Nm pingu
+.Nd multi ISP failover and load-balancing daemon
+
+.Sh SYNOPSIS
+.Nm
+.Op Fl dhvV
+.Op Fl a SOCKETPATH
+.Op Fl c CONFIG
+.Op Fl p PIDFILE
+
+.Sh DESCRIPTION
+The pingu utility monitors specified interfaces and sets up an alternate
+route table for each specified interface in which it mirrors all routes
+using that interface. It also sets up a route rule so that this alternate
+route table is looked up for traffic where the source IP address matches
+the primary IP address of the corresponding interface. This guarantees
+that a service bound to the primary address of an interface will always
+use routes from that interface.
+.Pp
+It can also ping specified hosts at regular intervals to detect if a
+gateway via a certain interface goes down. It will then remove the default
+gateway(s) via this interface from main route table so that traffic not
+bound to the failed interface will fail over to other configured interfaces.
+.Pp
+Pingu can also set up a multipath nexthop defafult route for interfaces
+configured as "load-balance"
+.Bl -tag -width indent
+.It Fl a
+Use SOCKETPATH as administration socket instead of the default @DEFAULT_ADM_SOCKET@
+.It Fl c
+Use config file CONFIG instead of the default /etc/pingu/pingu.conf
+.It Fl d
+Fork to background (daemonize).
+.It Fl h
+Show short help text.
+.It Fl p
+Use PIDFILE as pidfile instead of the default /var/run/pingu/pingu.pid
+.It Fl V
+Print version and exit.
+.It Fl v
+Run in verbose mode. Will log debug messages,
+.El
+
+.Sh FILES
+/etc/pingu/pingu.conf
+.br
+/var/run/pingu/pingu.pid
+.br
+/var/run/pingu/pingu.ctl
+
+.Sh AUTHORS
+.An Natanael Copa
+.Aq ncopa@alpinelinux.org
+
+
diff --git a/man/pingu.conf.5.in b/man/pingu.conf.5.in
new file mode 100644
index 0000000..0182afb
--- /dev/null
+++ b/man/pingu.conf.5.in
@@ -0,0 +1,97 @@
+.Dd October 19, 2011
+.Dt PINGU.CONF 8 Linux
+.Os
+
+.Sh NAME
+.Nm pingu.conf
+.Nd pingu daemon configuration file
+
+.Sh DESCRIPTION
+The file can contain 3 different contexts: Global context, interface context
+and host context.
+.Pp
+Blank lines and lines starting with # are ignored.
+
+
+.Sh GLOBAL CONTEXT
+The config file starts in global context. In this section the default values
+for the keywards used in interface on hosts sections are set. Values set in
+global context can be overridden in interface and host sections.
+
+.Bl -tag -indent
+.It Cd interval
+Set the default ping burst interval
+.It Cd timeout
+The default ping timout value in seconds. If the ping response does not come
+back within "timeout" seconds the ping is considered lost.
+.It Cd required
+The minimum required ping responses of a burst to consider the host online.
+.It Cd retries
+Maximum sent ping packets for a burst.
+.It Cd up-action
+The default action to execute when a ping host goes online.
+.It Cd down-action
+The default action to execute when a ping host goes offline.
+.El
+
+.Sh INTERFACE CONTEXT
+Example:
+.Bd -literal
+interface eth0 {
+	keyword value
+	...
+}
+.Ed
+
+The keywords valid in an interface sections are:
+.Bl -tag -indent
+.It Cd gateway-down-action
+Execute this action when a gateway is considered offline.
+.It Cd gateway-up-action
+Execute this action when a gateway is considered online.
+.It Cd label
+A user defined label that will be used in logs and by pinguctl
+.It Cd load-balance
+Enable balancing for this interface. Minimum 2 interfaces needs be configured
+for load-balancing to work. An option weight value can be given.
+.It Cd required-hosts-online
+The minimum number of ping hosts that needs to be online to consider the
+gateway online.
+.It Cd route-table
+The alternate route table for this interface.
+.El
+
+.Sh HOST CONTEXT
+Example:
+.Bd -literal
+host 1.2.3.4 {
+	keyword value
+	...
+}
+.Ed
+
+.Bl -tag -indent
+.It Cd bind-interface
+Bind the pings to this interface.
+.It Cd down-action
+Execute this action when ping host goes offline
+.It Cd interval
+The interval for ping bursts
+.It Cd label
+A label to be used in logs and pinguctl
+.It Cd required
+The number of required ping responses to consider host online.
+.It Cd retry
+The maximum number of retries for a ping burst.
+.It Cd timeout
+The ping response timeout value in seconds. If no ping respons returns within
+this value the ping is considered lost.
+.It Cd up-action
+Execute this action when a ping host goes online
+.El
+
+.Sh AUTHORS
+.An Natanael Copa
+.Aq ncopa@alpinelinux.org
+
+
diff --git a/man/pinguctl.8.in b/man/pinguctl.8.in
new file mode 100644
index 0000000..dce74a6
--- /dev/null
+++ b/man/pinguctl.8.in
@@ -0,0 +1,38 @@
+.Dd October 19, 2011
+.Dt PINGUCTL 8 Linux
+.Os
+
+.Sh NAME
+.Nm pinguctl
+.Nd pingu administration client
+
+.Sh SYNOPSIS
+.Nm
+.Op Fl a SOCKETPATH
+.Op Ar command ...
+
+.Sh DESCRIPTION
+Connects to a running pingu daemon and query status information.
+.Bl -tag -width indent
+.It Fl a
+Use SOCKETPATH as administration socket instead of the default @DEFAULT_ADM_SOCKET@
+.El
+
+.Sh COMMANDS
+The following commands are valid:
+.Bl -tag -width indent
+.It Ar gateway-status
+Show the status of the gateways.
+.It Ar host-status
+Show the status of the hosts.
+.El
+
+
+.Sh FILES
+@DEFAULT_ADM_SOCKET@
+
+.Sh AUTHORS
+.An Natanael Copa
+.Aq ncopa@alpinelinux.org
+
+