From f239bfc2cffbefd075102b95205e582755ca9594 Mon Sep 17 00:00:00 2001 From: Natanael Copa Date: Fri, 23 Aug 2013 16:43:15 +0200 Subject: doc: convert man pages to asciidoc --- doc/Makefile | 17 +++++-- doc/pingu.8.in | 60 ----------------------- doc/pingu.conf.5.in | 105 ---------------------------------------- doc/pingu.conf.txt.in | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/pingu.txt.in | 73 ++++++++++++++++++++++++++++ doc/pinguctl.8.in | 38 --------------- doc/pinguctl.txt.in | 47 ++++++++++++++++++ 7 files changed, 264 insertions(+), 206 deletions(-) delete mode 100644 doc/pingu.8.in delete mode 100644 doc/pingu.conf.5.in create mode 100644 doc/pingu.conf.txt.in create mode 100644 doc/pingu.txt.in delete mode 100644 doc/pinguctl.8.in create mode 100644 doc/pinguctl.txt.in diff --git a/doc/Makefile b/doc/Makefile index e43c526..ac245ee 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -3,6 +3,7 @@ MANDIR ?= /usr/share/man MAN5PAGES = pingu.conf.5 MAN8PAGES = pingu.8 pinguctl.8 ALL_MANPAGES = $(MAN5PAGES) $(MAN8PAGES) +TXT_FILES = pingu.txt pingu.conf.txt pinguctl.txt DEFAULT_ADM_SOCKET ?= /var/run/pingu/pingu.ctl DEFAULT_PIDFILE ?= /var/run/pingu/pingu.pid @@ -16,16 +17,26 @@ 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) $< > $@ +replace = $(SED) $(SED_REPLACE) $(SED_EXTRA) $< > $@ .SUFFIXES: .in .in: - $(mkman) + $(replace) + +%.5: %.txt + a2x -f manpage $< + +%.8: %.txt + a2x -f manpage $< all: $(ALL_MANPAGES) +pingu.conf.5: pingu.conf.txt +pingu.8: pingu.txt +pinguctl.8: pinguctl.txt + clean: - rm -f $(ALL_MANPAGES) + rm -f $(ALL_MANPAGES) $(TXT_FILES) install: $(ALL_MANPAGES) $(INSTALLDIR) $(DESTDIR)$(MANDIR)/man5 $(DESTDIR)$(MANDIR)/man8 diff --git a/doc/pingu.8.in b/doc/pingu.8.in deleted file mode 100644 index 311e0ce..0000000 --- a/doc/pingu.8.in +++ /dev/null @@ -1,60 +0,0 @@ -.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 deleted file mode 100644 index 0c0a96b..0000000 --- a/doc/pingu.conf.5.in +++ /dev/null @@ -1,105 +0,0 @@ -.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/pingu.conf.txt.in b/doc/pingu.conf.txt.in new file mode 100644 index 0000000..bb5f438 --- /dev/null +++ b/doc/pingu.conf.txt.in @@ -0,0 +1,130 @@ +PINGU.CONF(5) +============= +:doctype: manpage + + +NAME +---- +pingu.conf - pingu daemon configuration file + + +DESCRIPTION +----------- +The file can contain 3 different contexts: Global context, interface context +and host context. + +Blank lines and lines starting with # are ignored. + + +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. + +*interval*:: +Set the default ping burst interval + +*timeout*:: + The default ping timout value in seconds. If the ping response does + not come back within "timeout" seconds the ping is considered lost. + +*required*:: + The minimum required ping responses of a burst to consider the host + online. + +*retries*:: + Maximum sent ping packets for a burst. + +*up-action*:: + The default action to execute when a ping host goes online. + +*down-action*:: + The default action to execute when a ping host goes offline. + + +INTERFACE CONTEXT +----------------- +Example: +.... +interface eth0 { + keyword value + ... +} +.... + + +The keywords valid in an interface sections are: + +*gateway-down-action*:: + Execute this action when a gateway is considered offline. + +*gateway-up-action*:: + Execute this action when a gateway is considered online. + +*label*:: + A user defined label that will be used in logs and by pinguctl. + +*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. + +*required-hosts-online*:: + The minimum number of ping hosts that needs to be online to consider + the gateway online. + +*route-table*:: + The alternate route table for this interface. + +*rule-priority*:: + The preference value for the ip rule. + +*ping*:: + Host to ping to verify that gateway is still up. This is the same as + defining a host and bind it to interface. + +*fwmark*:: + Add an additional route rule for configured fwmark integer. + + +HOST CONTEXT +------------ +Example: +.... +host 1.2.3.4 { + keyword value + ... +} +.... + +*bind-interface*:: + Bind the pings to this interface. + +*down-action*:: + Execute this action when ping host goes offline. + +*interval*:: + The interval for ping bursts. + +*label*:: + A label to be used in logs and pinguctl. + +*required*:: + The number of required ping responses to consider host online. + +*retry*:: + The maximum number of retries for a ping burst. + +*timeout*:: + The ping response timeout value in seconds. If no ping response + returns within this value the ping is considered lost. + +*up-action*:: + Execute this action when a ping host goes online + + +AUTHORS +------- +Natanael Copa + diff --git a/doc/pingu.txt.in b/doc/pingu.txt.in new file mode 100644 index 0000000..7954059 --- /dev/null +++ b/doc/pingu.txt.in @@ -0,0 +1,73 @@ +PINGU(8) +======== +:doctype: manpage + + +NAME +---- +pingu - Multi ISP policy routing, failover and load-balancing daemon + + +SYNOPSIS +-------- +*pingu* ['-dhvV'] [*-a* 'SOCKETPATH'] [*-c* 'CONFIG'] [*-p* 'PIDFILE'] + + +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. + +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. + +Pingu can also set up a multipath nexthop defafult route for interfaces +configured as "load-balance" + + +OPTIONS +------- +*-a* 'SOCKETPATH':: + Use _SOCKETPATH_ as administration socket instead of the default + '@DEFAULT_ADM_SOCKET@' + +*-c* 'CONFIG':: + Use config file CONFIG instead of the default '@DEFAULT_CONFIG@' + +*-d*:: + Fork to background (daemonize). + +*-h*:: + Show short help text. + +*-p* 'PIDFILE':: + Use PIDFILE as pidfile instead of the default '@DEFAULT_PIDFILE@' + +*-V*:: + Print version and exit. + +*-v*:: + Run in verbose mode. Will log debug messages, + + +FILES +----- + +'@DEFAULT_CONFIG@' + +'@DEFAULT_PIDFILE@' + +'@DEFAULT_ADM_SOCKET@' + +AUTHORS +------- +Natanael Copa + + diff --git a/doc/pinguctl.8.in b/doc/pinguctl.8.in deleted file mode 100644 index dce74a6..0000000 --- a/doc/pinguctl.8.in +++ /dev/null @@ -1,38 +0,0 @@ -.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 - - diff --git a/doc/pinguctl.txt.in b/doc/pinguctl.txt.in new file mode 100644 index 0000000..8488ce7 --- /dev/null +++ b/doc/pinguctl.txt.in @@ -0,0 +1,47 @@ +PINGUCTL(8) +=========== +:doctype: manpage + + +NAME +---- +pinguctl - pingu administration client + + +SYNOPSIS +-------- +*pinguctl* [*-a* 'SOCKETPATH'] command + + +DESCRIPTION +----------- +Connects to a running pingu daemon and query status information. + + +OPTIONS +------- +*-a* 'SOCKETPATH':: + Use SOCKETPATH as administration socket instead of the default + '@DEFAULT_ADM_SOCKET@' + + +COMMANDS +-------- +The following commands are valid: + +*gateway-status*:: + Show the status of the gateways. + +*host-status*:: + Show the status of the hosts. + + +FILES +----- +@DEFAULT_ADM_SOCKET@ + + +AUTHORS +------- +Natanael Copa + -- cgit v1.2.3