diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/.gitignore | 1 | ||||
| -rw-r--r-- | doc/Makefile | 33 | ||||
| -rw-r--r-- | doc/pingu.8.in | 60 | ||||
| -rw-r--r-- | doc/pingu.conf.5.in | 105 | ||||
| -rw-r--r-- | doc/pinguctl.8.in | 38 |
5 files changed, 237 insertions, 0 deletions
diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..dd5c122 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +*.[58] diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..e43c526 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,33 @@ + +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 + +INSTALL := install +INSTALLDIR := $(INSTALL) -d +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) $(MAN5PAGES) $(DESTDIR)$(MANDIR)/man5 + $(INSTALL) $(MAN8PAGES) $(DESTDIR)$(MANDIR)/man8 diff --git a/doc/pingu.8.in b/doc/pingu.8.in new file mode 100644 index 0000000..311e0ce --- /dev/null +++ b/doc/pingu.8.in @@ -0,0 +1,60 @@ +.Dd October 19, 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 @DEFAULT_CONFIG@ +.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 @DEFAULT_PIDFILE@ +.It Fl V +Print version and exit. +.It Fl v +Run in verbose mode. Will log debug messages, +.El + +.Sh FILES +@DEFAULT_CONFIG@ +.br +@DEFAULT_PIDFILE@ +.br +@DEFAULT_ADM_SOCKET@ + +.Sh AUTHORS +.An Natanael Copa +.Aq ncopa@alpinelinux.org + + diff --git a/doc/pingu.conf.5.in b/doc/pingu.conf.5.in new file mode 100644 index 0000000..0c0a96b --- /dev/null +++ b/doc/pingu.conf.5.in @@ -0,0 +1,105 @@ +.Dd August 20, 2013 +.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 keywords 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. A minimum of two interfaces need to +be configured in order for load-balancing to work. An optional 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. +.It Cd rule-priority +The preference value for the ip rule. +.It Cd ping +Host to ping to verify that gateway is still up. This is the same as defining +a host and bind it to interface. +.It Cd fwmark +Add an additional route rule for configured fwmark integer. +.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 response 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/doc/pinguctl.8.in b/doc/pinguctl.8.in new file mode 100644 index 0000000..dce74a6 --- /dev/null +++ b/doc/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 + + |