Added Pipe documentation.

diff --git a/doc/bird.sgml b/doc/bird.sgml
index 8a274e0d4f256de269957c0db5f01ae4c227f148..e5e290747a30cec4ec10d7ce54a6308d868b49c3 100644 (file)
--- a/doc/bird.sgml
+++ b/doc/bird.sgml
@@ -753,6 +753,7 @@ protocol kernel {           # Secondary routing table
        table auxtable;
        kernel table 100;
        export all;
+}
 </code>
 
 <p>The Kernel protocol doesn't define any route attributes.
@@ -761,6 +762,105 @@ protocol kernel {         # Secondary routing table
 
 <sect1>Pipe
 
+<sect2>Introduction
+
+<p>The Pipe protocol serves as a link between two routing tables, allowing routes to be
+passed from a table declared as primary (i.e., the one the pipe is connected using the
+<cf/table/ configuration keyword) to the secondary one (declared using <cf/peer table/)
+and vice versa, depending on what's allowed by the filters. Export filters control export
+of routes from the primary table to the secondary one, import filters control the opposite
+direction.
+
+<p>The primary use of multiple routing tables and the pipe protocol is for policy routing
+where handling of a single packet doesn't depend only on its destination address, but also
+on its source address, source interface, protocol type and other similar parameters.
+In many OS'es (Linux 2.2 being a good example) the kernel allows to enforce routing policies
+by defining routing rules which choose one of several routing tables to be used for a packet
+according to its parameters. Setting of these rules is outside the scope of BIRD's work
+(you can use the <tt/ip/ command), but you can create several routing tables in BIRD,
+connect them to the kernel ones, use filters to control which routes appear in which tables
+and also you can employ the Pipe protocol to export a selected subset of one table in
+another one.
+
+<sect2>Configuration
+
+<p><descrip>
+       <tag>peer table <m/table/</tag> Define secondary routing table to connect to. The
+       primary one is selected by the <cf/table/ keyword.
+</descrip>
+
+<sect2>Attributes
+
+<p>The Pipe protocol doesn't define any route attributes.
+
+<sect2>Example
+
+<p>Let's consider a router which serves as a boundary router of two different autonomous
+systems, each of them connected to a subset of interfaces of the router, having its own
+exterior connectivity and wishing to use the other AS as a backup connectivity in case
+of outage of its own exterior line.
+
+<p>Probably the simplest solution to this situation is to use two routing tables (we'll
+call them <cf/as1/ and <cf/as2/) and set up kernel routing rules, so that packets having
+arrived from interfaces belonging to the first AS will be routed according to <cf/as1/
+and similarly for the second AS. Thus we have split our router to two logical routers,
+each one acting on its own routing table, having its own routing protocols on its own
+interfaces. In order to use the other AS's routes for backup purposes, we can pass
+the routes between the tables through a Pipe protocol while decreasing their preferences
+and correcting their BGP paths to reflect AS boundary crossing.
+
+<code>
+table as1;                             # Define the tables
+table as2;
+
+protocol kernel kern1 {                        # Synchronize them with the kernel
+       table as1;
+       kernel table 1;
+}
+
+protocol kernel kern2 {
+       table as2;
+       kernel table 2;
+}
+
+protocol bgp bgp1 {                    # The outside connections
+       table as1;
+       local as 1;
+       neighbor 192.168.0.1 as 1001;
+       export all;
+       import all;
+}
+
+protocol bgp bgp2 {
+       table as2;
+       local as 2;
+       neighbor 10.0.0.1 as 1002;
+       export all;
+       import all;
+}
+
+protocol pipe {                                # The Pipe
+       table as1;
+       peer table as2;
+       export filter {
+               if net ~ [ 1.0.0.0/8+] then {   # Only AS1 networks
+                       if preference>10 then preference = preference-10;
+                       if source=RTS_BGP then bgp_path.prepend(1);
+                       accept;
+               }
+               reject;
+       };
+       import filter {
+               if net ~ [ 2.0.0.0/8+] then {   # Only AS2 networks
+                       if preference>10 then preference = preference-10;
+                       if source=RTS_BGP then bgp_path.prepend(2);
+                       accept;
+               }
+               reject;
+       };
+}
+</code>
+
 <sect1>Rip
 
 <sect2>Introduction