====================
Private WAN routers
====================

Private WAN (PWAN) is the Bonded Internet feature that allows
geographically separated sites to securely route traffic to each other
as if each site was connected to the same router.

If no spaces use PWAN in **With private WAN routers** mode,
a partner needs no PWAN routers.

|image0|

PWAN routers have three roles:

#. controlling the special routing configuration for PWAN spaces on
   aggregators
#. routing traffic between bonds in a PWAN space that are on different
   aggregators in the same routing group
#. routing traffic between bonds in a PWAN space that are in different
   routing groups

When PWAN is enabled on a space at a certain routing group, the PWAN
router at the routing group connects to the aggregators in the group and
updates their routing rules to contain traffic from the space into a
specific routing table. If a bond in the space is moved from one
aggregator to another, the PWAN router adjusts the rules on both
aggregators so that traffic continues to flow between the bonds and
aggregators. The PWAN router also removes the aggregator's special
routing rules if a bond is deleted.

When traffic is sent between bonds in a PWAN space that are on the same
aggregator, the aggregator routes the traffic locally without going
through the PWAN router. When traffic is sent between bonds on different
aggregators in the same routing group, the traffic is forwarded between
the aggs by the PWAN router.

PWAN routers in each routing group also connect to PWAN routers in other
routing groups, creating an on-demand mesh network, in order to allow
bonds assigned to aggregators in one routing group to communicate with
bonds assigned to aggregators in another routing group.

PWAN routers also have an important role in routing traffic from PWAN
spaces to and from the Internet. Outbound traffic from PWAN spaces can
be forwarded to specific gateways, with or without NAT, and inbound
traffic can be forwarded using 1:1 NAT rules or port forward rules.

PWAN routers are usually located in the same datacentre as the
aggregators with which they are grouped, in order to minimize latency
and maximize throughput between all the datacentre hosts. However, this
is not a requirement. PWAN routers can be located in a different
datacentre than the aggregators in their routing group if the
performance issues from higher latency or limited throughput can be
managed or ignored. In the case of a two-aggregator routing group, where
all bonds are given the same primary agg and the same secondary agg,
such that all bonds will always be on the same aggregator, no traffic
will ever pass through the PWAN router and latency and throughput issues
do not need to be considered at all. Note that even in this scenario, a
PWAN router is needed because of its control role with aggregators.

Private WAN routers are similar to aggregators in a number of respects:
they route large amounts of traffic, they can be deployed as bare metal
or virtual guests, and they are usually integrated into the dynamic
routing configuration of the partner's network.

For high availability, two PWAN routers can be configured at one routing
group, and they will automatically take primary or standby roles and
fail over in 60 seconds or less if the primary router fails.

.. warning ::
    Prior to 6.3.18 there was a scenario where having multiple routing groups
    with a single private WAN router each could lead to unexpected network
    outages on a single remaining online private WAN router.

System requirements
--------------------

See `System Requirements
<../../nodes/system-requirements.html#PrivateWANRouters>`__ for
private WAN routers.

Networking options
-------------------

There are two ways that a PWAN router can be integrated into the partner
network.

The first method uses the same interface for traffic to/from aggregators
and space VLAN traffic to/from the partner core network. This is the
default. For example:

|image1|

The second method uses a separate interface for traffic to/from
aggregators and space VLAN traffic. For example:

|image2|

Note that the above example shows two separate routers, one for eth0 and
one for eth1, but this is not necessary—the PWAN router could certainly
connect both eth0 and eth1 to the same router, but use no VLAN on eth0
and VLANs for each space on eth1.

For more information, see the configuration instructions in
`Provisioning private WAN
routers <provisioning-routers.html>`__.

Managing private WAN routers
-----------------------------

Listing PWAN routers
+++++++++++++++++++++

To view the list of PWAN routers, click Hosts in the main menu, then
click Private WAN Routers.

The list of routers is shown. Click a router name to see details about
the router.

Adding a PWAN router
+++++++++++++++++++++

To add a PWAN router, browse to the list page, then click the "Add
Router" button. This opens the form for creating a PWAN router. Complete
the form on the Router tab and click "Save". When creating a new router,
only the main tab is shown. After saving the router, the other tabs are
shown.

Viewing or updating a PWAN router
++++++++++++++++++++++++++++++++++

To view or update a PWAN router, navigate to the list page and click the
name of the router or the |image3| button beside its name. This opens
the router page with these tabs:

-  Router: name, IP address, and other fields
-  Node: details about the node, including operating system and hardware
   details, available when the router connects to the management server

Private WAN router fields
^^^^^^^^^^^^^^^^^^^^^^^^^^

Name
~~~~~

The name of the router.

IP
~~~

The IP address of the router.

IPv6
~~~~~

The IPv6 address that bonders should use to contact the router. An IPv4 address is required even if an IPv6 address is configured.

.. warning::

    Changing the configured address for either IP version requires a matching manual configuration change on the node.
    Consult `changing a host IP address <../../administration/changing-host-ip-address.html>`__ before changing any configured IP address on a PWAN router.

Note
~~~~~

A free-form field for any relevant information.

Routing group
~~~~~~~~~~~~~~

The routing group to which the router is assigned.

This field can be set when the PWAN router is created, but cannot be
changed after it is created.

Priority
~~~~~~~~~

The router's priority, used to break ties in routing decisions and avoid
splitting NAT traffic. Lower values indicate higher priority.

VLAN trunk interface
~~~~~~~~~~~~~~~~~~~~~

The name of the network interface on the PWAN router that sends and
receives VLAN-tagged traffic for each space. This defaults to the ext
bridge device, but can be set to eth1 (for example) if a second network
interface is dedicated for VLAN traffic. If this field is changed after
the router is provisioned, you must reconfigure networking and reboot
the PWAN router to activate the change.

Enabled
~~~~~~~~

When checked, the router joins the cluster of other PWAN routers at its
routing group, sending traffic to and and receiving traffic from
aggregators and other router's in the partner's core network. This can
be disabled to prevent the router from being used, such as when it's
undergoing maintenance.

Proxy ARP
~~~~~~~~~~

Enable this if you want the private WAN router to proxy ARP requests for
IP addresses assigned to bonders or outbound gateways. This is useful in
environments where standard routing using BGP or OSPF is not available.
Note that this has no effect on outbound gateways that use VLANs.

Node fields
^^^^^^^^^^^^

These fields are available on the Node tab when viewing an existing PWAN
router.

Username
^^^^^^^^^

Usually root, the user for management via SSH.

Password
^^^^^^^^^

The password for the user specified above.

.. warning::
    The username and password fields are for record-keeping only. You should
    change them only if you manually change the management username or
    password on the private WAN router.

Serial number
~~~~~~~~~~~~~~

The serial number of the private WAN router hardware.

Asset tag
~~~~~~~~~~

The asset tag given to the private WAN router hardware.

Web server
~~~~~~~~~~~

If checked, the private WAN router will offer a simple web service to local
networks and trusted remote networks.

.. note::
    As of 2015.4, the web service on the PWAN router doesn't actually do
    anything. Its functionality may be expanded in future versions of Bonded
    Internet.

Debug
~~~~~~

If checked, services running on the private WAN router log events in much more
detail than normal. Debug mode is not recommended except on the
recommendation of a technical support agent.

TCP segmentation offloading
~~~~~~~~~~~~~~~~~~~~~~~~~~~

If checked, enables TCP segmentation offloading (TSO) for private WAN
backhaul. Disabling TSO is necessary on some platforms that suffer severe
performance degradation when the backhaul is encrypted.

Metric collection
~~~~~~~~~~~~~~~~~~

How frequently to query performance metrics, in seconds.

Metric reporting
~~~~~~~~~~~~~~~~~

How frequently to report collected metrics to the management server, in
seconds.


CPU governor
~~~~~~~~~~~~

Select which algorithm to use for scaling CPU frequencies.
If unset, the last used method for the CPU type will be used or the system default will be used after the system is rebooted.
Selection of an alternate governor, particularly so ``Performance``,
may result in increased throughput on certain platforms.
For a detailed explanation of each governor, see `the documentation <https://www.kernel.org/doc/Documentation/cpu-freq/governors.txt>`__.

Conntrack table size
~~~~~~~~~~~~~~~~~~~~~

The maximum number of connections the host can track in its internal
tables. If the number of tracked connections reaches this number, new
connections will be dropped and an entry made in the system log file.

Deleting a PWAN router
^^^^^^^^^^^^^^^^^^^^^^^

To delete a PWAN router, navigate to its page and click the Delete
button. Accept the confirmation and say "au revoir" to the router.

High Availability
------------------

|image4|

The private WAN router list showing that PWR01 is the current primary
router for the Vancouver routing group.

For a high availability setup of PWAN routers, multiple PWAN routers
need to be configured in the same routing group. There is no limit to
the number of PWAN routers and high availability is automatic once there
are multiple configured and running in the same routing group.

The primary router for each routing group is chosen based on its
configured priority: the ID of the PWAN router is used as a tiebreaker.
In both cases a lower number is higher priority.

PWAN routers check against each other with heartbeat checks every 10
seconds, and fail the check after 5 seconds with no response. Thus, it
can take up to a maximum of 25 seconds to move to another PWAN router if
the primary goes offline right after the previous check had succeeded.

After a new PWAN router has been elected as the primary it can take 30
seconds for BGP to converge on the new setup.

Outside of outages, the primary PWAN router will only change if a new
PWAN router is added with a lower priority, the lowest priority PWAN
router goes offline, or the lowest priority PWAN router comes back
online.


.. |image0| image:: /attachments/11667353/11668042.png
.. |image1| image:: /attachments/11667353/12320960.png
.. |image2| image:: /attachments/11667353/12320961.png
.. |image3| image:: /attachments/11667020/11667643.png
.. |image4| image:: /attachments/11667353/12321214.png
