add path

Pre-Alpha. This page describes behavior that may change.

ADD-PATH (RFC 7911) lets BGP advertise more than one path per prefix by prefixing each NLRI with a 4-byte Path Identifier. The usual reason you turn it on is a route server: without ADD-PATH, the route server can only send one path per prefix to each client, and downstream routers cannot make their own best-path decisions. With ADD-PATH, every received path is forwarded, and downstream picks.

Enabling ADD-PATH

Global

capability {
    add-path {
        send true;
        receive true;
    }
}

That enables ADD-PATH for every family configured on the peer.

Per family

add-path {
    ipv4/unicast  send;
    ipv6/unicast  send/receive;
    ipv4/mpls-vpn receive;
}

Per-family settings override the global capability { add-path }. Use this when you want ADD-PATH on IPv4 unicast but not on the VPN family, or any other asymmetric setup.

A complete peer

bgp {
    peer client-a {
        connection {
            remote { ip 10.0.0.1; }
            local  { ip 10.0.0.254; }
        }
        session {
            asn { local 65000; remote 65001; }

            capability {
                add-path {
                    send true;
                    receive true;
                }
            }

            family {
                ipv4/unicast { prefix { maximum 1000000; } }
                ipv6/unicast { prefix { maximum 200000; } }
            }
        }
    }
}

Direction and mode

Each family can be configured with a direction (send, receive, or send/receive) and a mode (enable, require, or disable).

Direction	Meaning
send	Ze advertises multiple paths to the peer.
receive	Ze accepts multiple paths from the peer.
send/receive	Both.

Mode	Meaning
enable (default)	Negotiate ADD-PATH if the peer supports it.
disable	Do not negotiate ADD-PATH for this family.
require	Reject the peer if it does not support ADD-PATH.
refuse	Reject the peer if it advertises ADD-PATH for this family.

add-path {
    ipv4/unicast send         require;
    ipv6/unicast send/receive enable;
}

require is the useful mode when the entire point of your deployment is multi-path forwarding: you want the session rejected if ADD-PATH cannot be negotiated.

What ADD-PATH does to the wire

Without ADD-PATH, each NLRI is the prefix length plus the prefix bytes.

[prefix-length][prefix-bytes]

With ADD-PATH, each NLRI is preceded by a 4-byte Path Identifier.

[4-byte path-id][prefix-length][prefix-bytes]

The same prefix can appear multiple times in one UPDATE with different path IDs, each carrying different attributes. The peer distinguishes them by the Path Identifier.

A withdrawal with ADD-PATH must include the same path ID used in the announcement to withdraw a specific path. Withdrawing without a path ID is not valid on an ADD-PATH session.

Encoding context and zero-copy forwarding

This is where ADD-PATH interacts with Ze's cache-forward architecture. Peers that negotiate the same ADD-PATH direction and mode share an ContextID. Two peers with the same ContextID can receive the same cached wire bytes from the reactor without re-encoding.

A route server with four peers, all negotiating send/receive, gets one encoding context. When a route comes in from any of the four, the reactor can forward the cached bytes to the other three without any parsing or re-encoding. This is the zero-copy fast path.

Mixing ADD-PATH peers with non-ADD-PATH peers means you have two encoding contexts. Routes moving from an ADD-PATH peer to a non-ADD-PATH peer require a re-encode because the wire format differs.

ADD-PATH with the route server

ADD-PATH is particularly useful with the bgp-rs plugin. Without ADD-PATH, the route server can only forward one path per prefix to each client. With ADD-PATH, every received path is forwarded, which is what you want when the downstream routers should be making their own policy decisions.

The combination is documented in the route reflection page and the route server blueprint when that lands.

See also

• BGP peers for the surrounding configuration.
• Address families for the family list.
• Route reflection for the route server model that pairs with ADD-PATH.

Adapted from main/docs/guide/add-path.md.