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.

PATHS-LIMIT

PATHS-LIMIT (capability code 76, draft-abraitis-idr-addpath-paths-limit) lets the ADD-PATH receiver advertise the maximum number of paths it wants per prefix per family. This prevents uncontrolled path proliferation when a route server forwards all available paths.

The limit is direction-aware. The receiver's advertised limit constrains what the sender may send, and Ze keeps separate send-side and receive-side limit maps. The per-direction limit is folded into the encoding-context hash, so peers that negotiate the same ADD-PATH direction and the same path limit still share an encoding context and the zero-copy forward path.

Configuration

The path count limit is configured under capability { add-path } alongside the ADD-PATH direction:

capability {
    add-path {
        direction send/receive;
        limit 10;
    }
}

The limit on the container is the default for all families. Per-family entries can override it:

capability {
    add-path {
        direction send;
        family {
            ipv4/unicast {
                direction send/receive;
                limit 10;
            }
            ipv6/unicast {
                direction receive;
                limit 5;
            }
        }
    }
}

Behaviour

When configured:

• The receiver advertises the PATHS-LIMIT capability during OPEN, declaring the maximum paths per prefix it wants for each family.
• The sender enforces the limit, suppressing excess paths.
• Route server fast-path peers suppress the PATHS-LIMIT capability (the RS forwards everything, path limiting is the client's responsibility).

Mode enforcement

Per-family ADD-PATH mode is enforced during OPEN negotiation. A family configured with mode require rejects the peer if ADD-PATH cannot be negotiated for that family. A family configured with mode refuse rejects the peer if the remote side advertises ADD-PATH for that family. This enforcement is per-family, not global.

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.