routing: pbr: add example utilizing multiple ISP uplinks

3 files changed, 64 insertions, 2 deletions

diff --git a/docs/_static/images/pbr_example_1.png b/docs/_static/images/pbr_example_1.png
new file mode 100644
index 00000000..3dff6db6
--- /dev/null
+++ b/docs/_static/images/pbr_example_1.png
diff --git a/docs/draw.io/pbr_example_1.drawio b/docs/draw.io/pbr_example_1.drawio
new file mode 100644
index 00000000..0d496572
--- /dev/null
+++ b/docs/draw.io/pbr_example_1.drawio
@@ -0,0 +1 @@
+<mxfile modified="2019-06-20T09:46:15.910Z" host="www.draw.io" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36" etag="pgW5M9QC_GIVY4GNWbyF" version="10.7.9" type="device"><diagram name="Page-1" id="c37626ed-c26b-45fb-9056-f9ebc6bb27b6">7VrbcqM4EP0aP4ZCgLk8xkk8u1UzW97K7FyepmRQsGoEYoUc2/P1K4G4CLBNJo7j2rLzAGpJrVafPq2WnYl9l2w/MJitPtEIkYllRtuJfT+xLMtzTPGQkl0pCQKnFMQMR6UINIJH/AspoZoXr3GEcm0gp5RwnOnCkKYpCrkmg4zRjT7siRJ91QzGqCd4DCHpS7/iiK+UFJhm0/EHwvFKLe1PVccShj9jRtepWm9i2U/Fp+xOYKVLjc9XMKKblsh+mNh3jFJeviXbO0Skbyu3lfPme3pruxlK+ZgJn4MU/ArY39bX3eKfT37yffHh8w2wSzXPkKxRtQ+XCIWzCD9Lq/lOecr9dy1NnXG05TeQ4Did2LdiBEFPXDxET+H+lN/kBciyD9jZtpkp3mL1LFbIM5h2ZcuuQGoctGPUUn8+LkClSbimVKYvIMS9RYVsyDghLryiS9/HUa/zCwgswzSAMcI5YxxhaZZYK54Q8QZE3zNiHAu2fYRLRBY0xxxT4Y/7JeWcJmKActB9KMIYMSEgcuSsJtcdJZQVait6NUpv1VxOM+klzujPmsRWLWlpME3fnEsEnjAhQ5prkspBEcxXKFIN0ZPJ7SXbWCZCA9PcM7DISrkRErqOaj9I49B2L0lBTX2RUhFNEGc7MURNuAkCv5yj0qkTlM1NKzf5SrZqpSVgqbQLVT6Ma91NThAvKi28JEU4r04RrLDzgnOEdZwG58kRJ/bUKZKEZYzwzjVJnDNJeO6lJQnLHUgSHcBRJAov1cxRnIjdPjSiGUqjW1nPSZgJzHMcCmErSNAW82+t9+/S58ZUte63CoKisVMNGa0tBGf2fO66fWSjKfIjZygWXHdmzee9uLFrIOWmDsMofEDXLEQHvBcMw92Csyo622hWMoYI5PhZN2MIYbXCguIiK1TR5HeiyfV94VZNS7kDNbFdY/Z0TXVdoK+LQxYj3tMlsIe71rBMDsgPmd1Zyp0GaqnR1gnz9CnipbSjYUKNxyvIEZyNHOb/jxzWu5LD87wqgOs48w3fbj6/SxXPORtVukv1qPI2cQ+s43HfPTFDnIfUEIe6OOdz9dRDXTtwO7Fq2q4feEOx2hzevQLgaPUxXEkUhUf75G9qgpAmkqA1y+YwwUT6/gtiEUyhEqsvQ4B1qruDr0eq5Vcwt9li+85AZVCVCyevDGxwPAhkEZft9YD65gcuq+Hmiz3jAZ0AU98Z8AzwBxIJqDLJ6WumnmO+fLz9C9RX8iUbLvH3lfMbZbUs6FPKEkiGS3rg+obA2xD7msuCcE8R38Fos8IcPWawyNUbwVWdlSPZoLMPjOOHM1CLT+Vfj+gpTVE1WZkO9hJ4FOUOxPTBM+nMsTR0Rx+VaQU4WZFrf8A0+pEhhrMVYpDkRtYpMS4j754cM6XGcbUEMXCj8vw+oN5b4TniOnXF8xCeUx3P6TvjaY8ohd78FARmtb9LOgb7l6PiGDTPcwz612Pw9yl4/Gp25liqflS85s0Xg3aZ5yAYcXu4AnoRB6FoNj9ml18hNP8xYD/8Bw==</diagram></mxfile>
\ No newline at end of file
diff --git a/docs/routing.rst b/docs/routing.rst
index abee716a..217847d6 100644
--- a/docs/routing.rst
+++ b/docs/routing.rst
@@ -300,13 +300,16 @@ display arp table entries
   10.1.1.100               ether   08:00:27:de:23:aa   CM                    eth1
 
 
-Policy Routing
-==============
+Policy-Based Routing (PBR)
+--------------------------
 
 VyOS supports Policy Routing, allowing traffic to be assigned to a different
 routing table. Traffic can be matched using standard 5-tuple matching (source
 address, destination address, protocol, source port, destination port).
 
+Transparent Proxy
+^^^^^^^^^^^^^^^^^
+
 The following example will show how VyOS can be used to redirect web traffic to
 an external transparent proxy:
 
@@ -336,6 +339,64 @@ we use:
 
   set interfaces ethernet eth1 policy route FILTER-WEB
 
+
+Multiple Uplinks
+^^^^^^^^^^^^^^^^
+
+VyOS Policy-Based Routing (PBR) works by matching source IP address ranges and
+forwarding the traffic using different routing tables.
+
+Routing tables that will be used in this example are:
+
+* ``table 10`` Routing tabled used for VLAN 10 (192.168.188.0/24)
+* ``table 11`` Routing tabled used for VLAN 11 (192.168.189.0/24)
+* ``main`` Routing table used by VyOS and other interfaces not paritipating in PBR
+
+.. figure:: _static/images/pbr_example_1.png
+   :scale: 80 %
+   :alt: PBR multiple uplinks
+
+   Policy-Based Routing with multiple ISP uplinks (source ./draw.io/pbr_example_1.drawio)
+
+Add default routes for routing ``table 10`` and ``table 11``
+
+.. code-block:: sh
+
+  set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.1.1
+  set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2
+
+Add policy route matching VLAN source addresses
+
+.. code-block:: sh
+
+  set policy route PBR rule 20 set table '10'
+  set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10'
+  set policy route PBR rule 20 source address '192.168.188.0/24'
+
+  set policy route PBR rule 20 set table '11'
+  set policy route PBR rule 20 description 'Route VLAN11 traffic to table 11'
+  set policy route PBR rule 20 source address '192.168.189.0/24'
+
+Apply routing policy to **inbound** direction of out VLAN interfaces
+
+.. code-block:: sh
+
+  set interfaces ethernet eth0 vif 10 policy route 'PBR'
+  set interfaces ethernet eth0 vif 11 policy route 'PBR'
+
+
+**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) from PBR
+
+.. code-block:: sh
+
+  set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut'
+  set policy route PBR rule 10 destination address '192.168.188.0/24'
+  set policy route PBR rule 10 destination address '192.168.189.0/24'
+  set policy route PBR rule 10 set table 'main'
+
+.. note:: Allows the VLAN10 and VLAN20 hosts to communicate with each other using the
+   main routing table.
+
 MSS Clamping
 ============