[doc] document version zserv header, add txt figures, make pdf figs nicer

2006-03-31 Paul Jakma <paul.jakma@sun.com>

	* fig*.txt: New files, txt versions of the diagrammes for the
	  info file.
	* protocol.texi: Document the new version 1 header.
	* routeserver.texi: Explicitly specify scaling widths for the
	  figures, only way to make them look reasonable, sadly.
	  Try fix some formatting and explicitely note lists as being
	  bulleted.
	* Makefile.am: convert seems to do png to pdf just fine. No
	  need for intermediate eps.
	  Add txt figure expansions and list as dependencies and
	  EXTRA_DIST files.

8 files changed, 221 insertions, 68 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index d91683b6..2cf20851 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,17 @@
+2006-03-31 Paul Jakma <paul.jakma@sun.com>
+
+	* fig*.txt: New files, txt versions of the diagrammes for the
+	  info file.
+	* protocol.texi: Document the new version 1 header.
+	* routeserver.texi: Explicitly specify scaling widths for the
+	  figures, only way to make them look reasonable, sadly.
+	  Try fix some formatting and explicitely note lists as being
+	  bulleted.
+	* Makefile.am: convert seems to do png to pdf just fine. No
+	  need for intermediate eps.
+	  Add txt figure expansions and list as dependencies and
+	  EXTRA_DIST files.
+
 2006-02-19 Paul Jakma <paul.jakma@sun.com>
 
 	* quagga.info: update auto-built file.
diff --git a/doc/Makefile.am b/doc/Makefile.am
index d1ad6ecd..c998e63e 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -6,15 +6,16 @@
 # dia exported PNG files to EPS manually.
 #
 # Here we use 'convert' from the well known 'ImageMagick' package
-# to do conversion from png to eps.
+# to do conversion from png to eps/pdf for figures. 
+# PDF form is required for quagga.pdf, using PDFTex at least.
 #
-# PDF is required for quagga.pdf, we use epstopdf from the well known TeTeX
 # TeX implementation, which we depend on already anyway.
 #
 # dia -> (dia) -> png -> (convert) -> eps -> (epstopdf) -> pdf
 DIATOPNG = dia -t png -e
 DIATOEPS = dia -t eps -e
-PNGTOEPS = convert
+PNGTOEPS = convert -dither -antialias -contrast -despeckle
+PNGTOPDF = $(PNGTOEPS)
 EPSTOPDF = epstopdf
 
 # The figure sources
@@ -24,6 +25,7 @@ figures_sources := $(figures_names_parts:%=fig%.dia)
 figures_png := $(figures_names_parts:%=fig%.png)
 figures_pdf := $(figures_names_parts:%=fig%.pdf)
 figures_eps := $(figures_names_parts:%=fig%.eps)
+figures_txt := $(figures_names_parts:%=fig%.txt)
 
 # rather twisted logic because we have to build PDFs of the EPS figures for
 # PDFTex and yet build one PDF, quagga.pdf, from texi source. Which means we
@@ -46,13 +48,14 @@ quagga.pdf: $(info_TEXINFOS) $(figures_pdf)
 quagga_TEXINFOS = appendix.texi basic.texi bgpd.texi filter.texi install.texi \
 	ipv6.texi kernel.texi main.texi ospf6d.texi ospfd.texi overview.texi \
 	protocol.texi ripd.texi ripngd.texi routemap.texi snmp.texi \
-	vtysh.texi routeserver.texi defines.texi $(figures_png) snmptrap.texi
+	vtysh.texi routeserver.texi defines.texi $(figures_png) snmptrap.texi \
+	$(figures_txt)
 
 %.eps: %.png
 	$(PNGTOEPS) $< "$@"
 
-%.pdf: %.eps
-	$(EPSTOPDF) --outfile="$@" $<
+%.pdf: %.png
+	$(PNGTOPDF) $< "$@"
 
 %.png: %.dia
 	$(DIATOPNG) "$@" $<
@@ -62,7 +65,7 @@ man_MANS = vtysh.1 bgpd.8 ospf6d.8 ospfd.8 ripd.8 ripngd.8 zebra.8 isisd.8
 EXTRA_DIST = BGP-TypeCode draft-zebra-00.ms draft-zebra-00.txt $(man_MANS) \
 	mpls/ChangeLog.opaque.txt mpls/cli_summary.txt \
 	mpls/opaque_lsa.txt mpls/ospfd.conf \
-	$(figures_sources) $(figures_png)
+	$(figures_sources) $(figures_png) $(figures_txt)
 
 draft-zebra-00.txt:
 	groff -T ascii -ms draft-zebra-00.ms > draft-zebra-00.txt
diff --git a/doc/fig-normal-processing.txt b/doc/fig-normal-processing.txt
new file mode 100644
index 00000000..01f0e179
--- /dev/null
+++ b/doc/fig-normal-processing.txt
@@ -0,0 +1,11 @@
+
+                  _______________________________
+                 /    _________     _________    \
+From Peer A --->|(A)-|Best     |   |         |-[A]|--->To Peer A
+From Peer B --->|(B)-|Path     |-->|Local-RIB|-[B]|--->To Peer B
+From Peer C --->|(C)-|Selection|   |         |-[C]|--->To Peer C
+From Peer D --->|(D)-|_________|   |_________|-[D]|--->To Peer D
+                 \_______________________________/
+
+Key:  (X) - 'In'  Filter applied to Peer X's announcements
+      [X] - 'Out' Filter applied to announcements to Peer X
diff --git a/doc/fig-rs-processing.txt b/doc/fig-rs-processing.txt
new file mode 100644
index 00000000..eafe1468
--- /dev/null
+++ b/doc/fig-rs-processing.txt
@@ -0,0 +1,47 @@
+From Peer A
+ | From RS-Client B
+ |  | From RS-Client C
+ |  |  | From RS-Client D
+ |  |  |  |
+ |  |  |  |           Main / Normal RIB
+ |  |  |  |      ________________________________
+ |  |  |  |     /    _________     _________     \
+ |  |  |  +--->|(D)-|Best     |   | Main    |     |
+ |  |  +--|--->|(C)-|Path     |-->|Local-RIB|->[A]|--->To Peer A
+ |  +--|--|--->|(B)-|Selection|   |         |     |
+ +--|--|--|--->|(A)-|_________|   |_________|     |
+ |  |  |  |     \________________________________/
+ |  |  |  |
+ |  |  |  |          ________________________________
+ |  |  |  |          /    _________     _________     \
+ |  |  |  +--->*D*->|{B}-|Best     |   |RS-Client|     |
+ |  |  +--|--->*C*->|{B}-|Path     |-->|Local-RIB|->[B]|--->To RS-Client B
+ |  |  |  |         |    |Selection|   |  for B  |     |
+ +--|--|--|-------->|{B}-|_________|   |_________|     |
+ |  |  |  |          \________________________________/
+ |  |  |  |
+ |  |  |  |          ________________________________
+ |  |  |  |          /    _________     _________     \
+ |  |  |  +--->*D*->|{C}-|Best     |   |RS-Client|     |
+ |  |  |  |         |    |Path     |-->|Local-RIB|->[C]|--->To RS-Client C
+ |  +--|--|--->*B*->|{C}-|Selection|   |  for C  |     |
+ +--|--|--|-------->|{C}-|_________|   |_________|     |
+ |  |  |             \________________________________/
+ |  |  |
+ |  |  |              ________________________________
+ |  |  |             /    _________     _________     \
+ |  |  |            |    |Best     |   |RS-Client|     |
+ |  |  +------>*C*->|{D}-|Path     |-->|Local-RIB|->[D]|--->To RS-Client D
+ |  +--------->*B*->|{D}-|Selection|   |  for D  |     |
+ +----------------->|{D}-|_________|   |_________|     |
+                     \________________________________/
+
+
+Key:  (X) - 'In'  Filter applied to Peer X's announcements before
+            considering announcement for the normal main Local-RIB
+      [X] - 'Out' Filter applied to announcements to Peer X
+      *X* - 'Export' Filter of RS-Client X, to apply X's policies
+	    before its routes may be considered for other RS-Clients
+            RIBs.
+      {X} - 'Import' Filter of RS-Client X, to apply X's policies
+            on routes before allowing them into X's RIB.
diff --git a/doc/fig_topologies_full.txt b/doc/fig_topologies_full.txt
new file mode 100644
index 00000000..cc8025a0
--- /dev/null
+++ b/doc/fig_topologies_full.txt
@@ -0,0 +1,6 @@
+(RF1)--(RF2)
+  | \  / |
+  |  \/  |
+  |  /\  |
+  | /  \ |
+(RF3)--(RF4)
diff --git a/doc/fig_topologies_rs.txt b/doc/fig_topologies_rs.txt
new file mode 100644
index 00000000..0bd17301
--- /dev/null
+++ b/doc/fig_topologies_rs.txt
@@ -0,0 +1,5 @@
+(RF1)  (RF2)
+    \  /
+    [RS]
+    /  \
+(RF3)  (RF4)
diff --git a/doc/protocol.texi b/doc/protocol.texi
index 23476651..602768a7 100644
--- a/doc/protocol.texi
+++ b/doc/protocol.texi
@@ -1,51 +1,112 @@
 @node  Zebra Protocol
 @appendix Zebra Protocol
+@appendixsection Overview of the Zebra Protocol
 
-Zebra Protocol is a protocol which is used between protocol daemon and
-zebra.  Each protocol daemon sends selected routes to zebra daemon.  Then
-zebra manages which route is installed into the forwarding table.
+Zebra Protocol is used by protocol daemons to communicate with the
+zebra daemon.
 
-Zebra Protocol is a TCP-based protocol.  Below is common header of Zebra
-Protocol.
+Each protocol daemon may request and send information to and from the
+zebra daemon such as interface states, routing state,
+nexthop-validation, and so on. Protocol daemons may also install routes
+with zebra. The zebra daemon manages which route is installed into the
+forwarding table with the kernel.
 
+Zebra Protocol is a streaming protocol, with a common header. Two
+versions of the header are in use. Version 0 is implicitely versioned.
+Version 1 has an explicit version field. Version 0 can be distinguished
+from all other versions by examining the 3rd byte of the header, which
+contains a marker value for all versions bar version 0. The marker byte
+corresponds to the command field in version 0, and the marker value is
+a reserved command in version 0.
+
+We do not anticipate there will be further versions of the header for
+the foreseeable future, as the command field in version 1 is wide
+enough to allow for future extensions to done compatibly through
+seperate commands.
+
+Version 0 is used by all versions of GNU Zebra as of this writing, and
+versions of Quagga up to and including Quagga 0.98. Version 1 will be
+used as of Quagga 1.0.
+
+@appendixsection Zebra Protocol Definition
+@appendixsubsec Zebra Protocol Header (version 0)
 @example
 @group
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
++-------------------------------+---------------+
 |           Length (2)          |   Command (1) |
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
++-------------------------------+---------------+
 @end group
 @end example
 
-Length is total packet length including this header length.  So minimum
-length is three.  Command is Zebra Protocol command.
-
-@example
-ZEBRA_INTERFACE_ADD                1
-ZEBRA_INTERFACE_DELETE             2
-ZEBRA_INTERFACE_ADDRESS_ADD        3
-ZEBRA_INTERFACE_ADDRESS_DELETE     4
-ZEBRA_INTERFACE_UP                 5
-ZEBRA_INTERFACE_DOWN               6
-ZEBRA_IPV4_ROUTE_ADD               7
-ZEBRA_IPV4_ROUTE_DELETE            8
-ZEBRA_IPV6_ROUTE_ADD               9
-ZEBRA_IPV6_ROUTE_DELETE           10
-ZEBRA_REDISTRIBUTE_ADD            11
-ZEBRA_REDISTRIBUTE_DELETE         12
-ZEBRA_REDISTRIBUTE_DEFAULT_ADD    13
-ZEBRA_REDISTRIBUTE_DEFAULT_DELETE 14
-ZEBRA_IPV4_NEXTHOP_LOOKUP         15
-ZEBRA_IPV6_NEXTHOP_LOOKUP         16
-@end example
-
+@appendixsubsec Zebra Protocol Common Header (version 1)
 @example
 @group
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-|             Type              |             Flags             |
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
++-------------------------------+---------------+-------------+
+|           Length (2)          |   Marker (1)  | Version (1) |
++-------------------------------+---------------+-------------+
+|          Command (2)          |
++-------------------------------+
 @end group
 @end example
+
+@appendixsubsec Zebra Protocol Header Field Definitions
+@table @samp
+@item Length
+Total packet length including this header. The minimum length is 3
+bytes for version 0 messages and 6 bytes for version 1 messages.
+
+@item Marker
+Static marker with a value of 255 always. This is to allow version 0
+Zserv headers (which do not include version explicitely) to be
+distinguished from versioned headers. Not present in version 0
+messages.
+
+@item Version
+Version number of the Zserv message. Clients should not continue
+processing messages past the version field for versions they do not
+recognise. Not present in version 0 messages.
+
+@item Command
+The Zebra Protocol command.
+@end table
+
+@appendixsubsec Zebra Protocol Commands
+@multitable {ZEBRA_REDISTRIBUTE_DEFAULT_DELETE_WHATEVER} {99999}
+@headitem Command @tab Value
+@item ZEBRA_INTERFACE_ADD	
+@tab 1
+@item ZEBRA_INTERFACE_DELETE
+@tab 2
+@item ZEBRA_INTERFACE_ADDRESS_ADD
+@tab 3
+@item ZEBRA_INTERFACE_ADDRESS_DELETE
+@tab 4
+@item ZEBRA_INTERFACE_UP
+@tab 5
+@item ZEBRA_INTERFACE_DOWN
+@tab 6
+@item ZEBRA_IPV4_ROUTE_ADD
+@tab 7
+@item ZEBRA_IPV4_ROUTE_DELETE
+@tab 8
+@item ZEBRA_IPV6_ROUTE_ADD
+@tab 9
+@item ZEBRA_IPV6_ROUTE_DELETE
+@tab 10
+@item ZEBRA_REDISTRIBUTE_ADD
+@tab 11
+@item ZEBRA_REDISTRIBUTE_DELETE
+@tab 12
+@item ZEBRA_REDISTRIBUTE_DEFAULT_ADD
+@tab 13
+@item ZEBRA_REDISTRIBUTE_DEFAULT_DELETE
+@tab 14
+@item ZEBRA_IPV4_NEXTHOP_LOOKUP
+@tab 15
+@item ZEBRA_IPV6_NEXTHOP_LOOKUP
+@tab 16
+@end multitable
diff --git a/doc/routeserver.texi b/doc/routeserver.texi
index 3b988451..afbbd8f0 100644
--- a/doc/routeserver.texi
+++ b/doc/routeserver.texi
@@ -33,20 +33,23 @@ First we are going to describe the normal processing that BGP announcements
 suffer inside a standard BGP speaker, as shown in @ref{fig:normal-processing},
 it consists of three steps:
 
-@itemize
-@item When an announcement is received from some peer, the `In' filters
+@itemize @bullet
+@item
+When an announcement is received from some peer, the `In' filters
 configured for that peer are applied to the announcement. These filters can
 reject the announcement, accept it unmodified, or accept it with some of its
 attributes modified.
 
-@item The announcements that pass the `In' filters go into the
+@item
+The announcements that pass the `In' filters go into the
 Best Path Selection process, where they are compared to other
 announcements referred to the same destination that have been
 received from different peers (in case such other
 announcements exist). For each different destination, the announcement
 which is selected as the best is inserted into the BGP speaker's Loc-RIB.
 
-@item The routes which are inserted in the Loc-RIB are
+@item
+The routes which are inserted in the Loc-RIB are
 considered for announcement to all the peers (except the one
 from which the route came). This is done by passing the routes
 in the Loc-RIB through the `Out' filters corresponding to each
@@ -57,17 +60,17 @@ of a peer are announced to that peer.
 @end itemize
 
 @float Figure,fig:normal-processing
-@image{fig-normal-processing,,,Normal announcement processing}
+@image{fig-normal-processing,400pt,,Normal announcement processing}
 @caption{Announcement processing inside a ``normal'' BGP speaker}
 @end float
 
 @float Figure,fig:full-mesh
-@image{fig_topologies_full,,,Full Mesh BGP Topology}
+@image{fig_topologies_full,120pt,,Full Mesh BGP Topology}
 @caption{Full Mesh}
 @end float
 
 @float Figure,fig:route-server
-@image{fig_topologies_rs,,,Route Server BGP Topology}
+@image{fig_topologies_rs,120pt,,Route Server BGP Topology}
 @caption{Route Server and clients} 
 @end float
 
@@ -80,34 +83,36 @@ server are not able to apply by themselves the same input/output filters
 as in the full mesh scenario, so they have to delegate those functions to
 the route server.
 
-Even more, the ``best path'' selection must be also performed inside the route
-server on behalf of its clients. The reason is that if, after applying the
-filters of the announcer and the (potential) receiver, the route server
-decides to send to some client two or more different announcements referred
-to the same destination, the client will only retain the last one,
-considering it as an implicit withdrawal of the previous announcements for
-the same destination. This is the expected behavior of a BGP speaker as
-defined in @cite{RFC1771}, and even though there are some proposals of
-mechanisms that permit multiple paths for the same destination to be sent
-through a single BGP peering, none of them are currently supported by most
-of the existing BGP implementations.
+Even more, the ``best path'' selection must be also performed inside
+the route server on behalf of its clients. The reason is that if, after
+applying the filters of the announcer and the (potential) receiver, the
+route server decides to send to some client two or more different
+announcements referred to the same destination, the client will only
+retain the last one, considering it as an implicit withdrawal of the
+previous announcements for the same destination. This is the expected
+behavior of a BGP speaker as defined in @cite{RFC1771}, and even though
+there are some proposals of mechanisms that permit multiple paths for
+the same destination to be sent through a single BGP peering, none are
+currently supported by most existing BGP implementations.
 
 As a consequence a route server must maintain additional information and
 perform additional tasks for a RS-client that those necessary for common BGP
 peerings. Essentially a route server must:
 
 @anchor{Route Server tasks}
-@itemize
-@item Maintain a separated Routing Information Base (Loc-RIB)
+@itemize @bullet
+@item
+Maintain a separated Routing Information Base (Loc-RIB)
 for each peer configured as RS-client, containing the routes
 selected as a result of the ``Best Path Selection'' process
 that is performed on behalf of that RS-client.
 
-@item Whenever it receives an announcement from a RS-client,
+@item
+Whenever it receives an announcement from a RS-client,
 it must consider it for the Loc-RIBs of the other RS-clients.
 
 @anchor{Route-server path filter process}
-@itemize
+@itemize @bullet
 @item
 This means that for each of them the route server must pass the
 announcement through the appropriate `Out' filter of the
@@ -124,9 +129,7 @@ to the ``Best Path Selection'' process.
 @item
 Finally, it might go into the Loc-RIB of the receiver.
 @end itemize
-@c end of route-server best path process list
 @end itemize
-@c end of route-server tasks list
 
 When we talk about the ``appropriate'' filter, both the announcer and the
 receiver of the route must be taken into account. Suppose that the route
@@ -150,15 +153,18 @@ The announcement processing model implemented by Quagga is shown in
 with normal BGP peers (A). There are some details that worth additional
 comments:
 
-@itemize
-@item Announcements coming from a normal BGP peer are also
+@itemize @bullet
+@item
+Announcements coming from a normal BGP peer are also
 considered for the Loc-RIBs of all the RS-clients. But
 logically they do not pass through any export policy.
 
-@item Those peers that are configured as RS-clients do not
+@item
+Those peers that are configured as RS-clients do not
 receive any announce from the `Main' Loc-RIB.
 
-@item Apart from import and export policies,
+@item
+Apart from import and export policies,
 `In' and `Out' filters can also be set for RS-clients. `In'
 filters might be useful when the route server has also normal
 BGP peers. On the other hand, `Out' filters for RS-clients are
@@ -167,7 +173,7 @@ they do not hurt anybody (they can always be left empty).
 @end itemize
 
 @float Figure,fig:rs-processing
-@image{fig-rs-processing,,,Route Server Processing Model}
+@image{fig-rs-processing,450pt,,Route Server Processing Model}
 @caption{Announcement processing model implemented by the Route Server}
 @end float