=====
Peers
=====

**Peers** are the central feature of the SD-WAN software. A peer is a
virtual tunnel across one or more network connections to a single remote node.
An individual connection is called a **peer link**. Peers can be established to
connect individual nodes or node groups. When a group is used, only one node in
that group will be used to carry traffic for the tunnel at a time. Furthermore,
peers can have any number of interfaces, remote nodes or remote node groups
assigned to them.

.. graphviz::

    graph {
        splines=ortho;
        ranksep=1;
        bgcolor="transparent";

        node [
            shape=box,
            style="filled,rounded",
            fillcolor="#E9F7EF",
            color="#1E8449",
            fontname="Arial",
            fontsize=12
        ];

        edge [
            style=solid,
            penwidth=1.5,
            color="#424949",
            fontname="Arial",
            fontsize=10
        ];

        node2 [label="Node 2"];
        node1 [label="Node 1"];

        node2 -- node1 [xlabel="&nbsp;Single peer with&nbsp;\ntwo peer links"];
        node2 -- node1;
    }

|

Peer **interfaces** represent any interfaces on the node that act as starting
points for a peer link connection. A peer can be assigned any number of
interfaces. Interfaces can be weighted by preference, so that those with higher
preference values will have higher priority (e.g.: an interface with a
preference of 500 will be used before one with 400). Interface preferences
default to 500. Multiple interfaces can be given the same priority, meaning
that any working links with the same preference will be active at the same time
provided there are no working links with a higher preference.

Peer **remotes** are nodes or node groups that form the target of a peer link
connection. If a node group is specified as a remote, the peer link will use
one node to carry traffic, but will maintain a connection with all nodes in the
group to facilitate fast failover, using a hashing algorithm that guarantees
near-equal distribution to choose the node that carries traffic. Like
interfaces, remotes can be weighted by preference.

Note that peers themselves do not implicitly carry traffic. Instead, peers must
be used in combination with the routing tools in the SD-WAN software,
namely nexthops and routes. See the `routing documentation
<../routing-and-vrfs/index.html>`__ for more details on how to set up routing
on peers.

Peers can be defined on any node to connect to any other node. Peers do not
have to be defined on both sides; instead, you define the peer on a single side
of the peer link, termed the "connecting" node. Any remote nodes used as the
target of the connecting node are termed "listening" nodes. Generally speaking,
connecting nodes are typically "edge" nodes, located on the periphery of the
network, while target nodes are usually "core" nodes, located more centrally.
That said, it is important to remember that this distinction is merely
conceptual, and that *any* node can establish a peer connection with *any*
other node, regardless of their location. The following diagram illustrates a
possible scenario:

.. graphviz::

    graph {
        splines=true;
        ranksep=1;
        bgcolor="transparent";

        node [
            shape=box,
            style="filled,rounded",
            fillcolor="#E9F7EF",
            color="#1E8449",
            fontname="Arial",
            fontsize=12
        ];

        edge [
            style=solid,
            penwidth=1.5,
            color="#424949"
        ];

        dc1 [label="Data center 1\n(\"core\" node)"];
        cpe1 [label="CPE 1\n(\"edge\" node)"];
        cpe2 [label="CPE 2\n(\"edge\" node)"];
        cpe3 [label="CPE 3\n(\"edge\" node)"];

        dc1 -- cpe1;
        dc1 -- cpe2;
        dc1 -- cpe3;
    }

|

Multiple peers can be created on the same node, with the same interfaces. This
allows you to create multiple groups of links with different characteristics
for carrying different types of traffic. For example, you can define one peer
to use only low-latency, low-bandwidth links, with higher-latency links as a
fallback option, while another peer uses higher-latency, higher-bandwidth links
with a low-latency fallback option. The key here is that peer definitions are
flexible and deliberately redundant, allowing you to leverage existing
topologies to maximum effect. This example is illustrated here:

.. graphviz::

    graph {
        splines=ortho;
        ranksep=0.5;
        bgcolor="transparent";

        node [
            shape=box,
            style="filled,rounded",
            fillcolor="#E9F7EF",
            color="#1E8449",
            fontname="Arial",
            fontsize=12
        ];

        edge [
            style=solid,
            penwidth=1.5,
            color="#424949",
            fontname="Arial",
            fontsize=10
        ];

        node2 [label="Node 2"];
        node1 [label="Node 1"];

        link1 [
            label="Low-latency,\nlow-bandwidth\ntraffic",
            fillcolor="#D3E4F4",
            color="#2E86C1",
            fontsize=10,
            height=0,
            width=0
        ];

        link2 [
            label="High-latency,\nhigh-bandwidth\ntraffic",
            fillcolor="#FFE8CC",
            color="#E67E22",
            fontsize=10,
            height=0,
            width=0
        ];

        edge [
            labeldistance=2.25,
            labelangle=55,
        ];

        node2 -- link1 [color="#F1C40F"];
        node2 -- link1 [color="#9B59B6", style=dashed];
        link1 -- node1 [color="#F1C40F", fontcolor="#F1C40F", headlabel="Peer 1"];
        link1 -- node1 [color="#9B59B6", style=dashed];

        edge [
            labeldistance=2.25,
            labelangle=-55,
        ];

        node2 -- link2 [color="#F1C40F", style=dashed];
        node2 -- link2 [color="#9B59B6"];
        link2 -- node1 [color="#F1C40F", style=dashed];
        link2 -- node1 [color="#9B59B6", fontcolor="#9B59B6", headlabel="Peer 2"];
    }

|

The following links provide further information on peers, including example
peer configurations, from basic to comprehensive. There is also information on
adding, editing, and deleting peers via the management web interface, and some
useful command line tools for advanced users.

.. toctree::
    :glob:
    :maxdepth: 1

    example-topologies
    managing-peers
    cli
