======
Routes
======

**Routes** specify a routing destination and are defined with one or more
nexthops.

A route must be assigned at least one nexthop, but can be configured to have
any number of them. Each nexthop assigned to a route has an associated
preference that determines its priority. Higher value nexthops always take
priority over lower value ones (e.g., a nexthop with a preference of 500 will
be used before one with 400). Within a single route, preference values must be
unique; it is not possible to configure multiple nexthops with identical
preferences.

.. graphviz::

    graph {
        rankdir=LR;
        fontname="Arial";
        splines=ortho;
        bgcolor="transparent";
        nodesep=0.5;
        ranksep=0.75;

        node [
            shape=box,
            style="filled,rounded",
            fontname="Arial",
            fontsize=12
        ];
        edge [
            penwidth=1.5,
            fontname="Arial",
            fontsize=10
        ];

        subgraph cluster_node {
            label="Node";
            style="filled,rounded";
            fillcolor="#E9F7EF";
            color="#1E8449";

            interface1 [label="Interface\neth0", fillcolor="#FFFFFF", color="666666"];
            interface2 [label="Interface\neth1", fillcolor="#FFFFFF", color="666666"];

            subgraph cluster_red {
                label="VRF Red";
                style="filled,rounded";
                fillcolor="#FFE0E0";
                color="#C0392B";

                route1 [style="filled", label="Route 1\n10.1.1.0/24", fillcolor="#FFF2F2"];

                { rank=same;
                    nh1 [label="Nexthop (Peer 1)\nPreference: 500", fillcolor="#FEF9E7"];
                    nh2 [label="Nexthop (Peer 2)\nPreference: 400", fillcolor="#FEF9E7"];
                }
            }

            subgraph cluster_blue   {
                label="VRF Blue";
                style="filled,rounded";
                fillcolor="#D3E4F4";
                color="#2E86C1";

                route2 [style="filled", label="Route 2\n10.2.1.0/24", fillcolor="#F2F2FF"];

                { rank=same;
                    nh3 [label="Nexthop (Peer 2)\nPreference: 500", fillcolor="#FEF9E7"];
                    nh4 [label="Nexthop (Peer 1)\nPreference: 400", fillcolor="#FEF9E7"];
                }
            }
        }

        interface1 -- route1;
        route1 -- nh1 [label="\nActive"];
        route1 -- nh2 [style=dashed, label="\n\nBackup\n"];
        destination1 [label="Destination\n10.1.1.0/24", style="filled,rounded", fillcolor="#FFFFFF", color="666666"];
        nh1 -- destination1;
        nh2 -- destination1 [style=dashed];

        interface2 -- route2;
        route2 -- nh3 [label="\nActive"];
        route2 -- nh4 [style=dashed, label="\n\nBackup\n"];
        destination2 [label="Destination\n10.2.1.0/24", style="filled,rounded", fillcolor="#FFFFFF", color="666666"];
        nh3 -- destination2;
        nh4 -- destination2 [style=dashed];
    }

|

Routes will always use the working nexthop with the highest preference. This
allows you to establish custom failover scenarios that kick in when a higher
preference nexthop goes down. For example, if a route is configured to send
traffic over one peer nexthop and that peer goes down, traffic will be diverted
through a lower preference peer nexthop if one is available. See the `nexthop
documentation <../nexthops/index.html>`__ for more information on nexthops.

Routes must always have a VRF assigned to them, and can only be assigned to
one. A given route will only apply to traffic in the matching VRF. Routes
cannot be created for non-VRF traffic. See the `VRF documentation
<../vrfs/index.html>`__ for further details.

More information on adding, editing, and deleting routes can be found below.

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

    managing-routes