summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/_static/css/version-picker.css11
-rw-r--r--docs/_static/js/pagefind-wrapper.js69
-rw-r--r--docs/_static/js/version-picker.js193
-rw-r--r--docs/_templates/breadcrumbs.html5
-rw-r--r--docs/_templates/searchbox.html13
-rw-r--r--docs/conf.py48
-rw-r--r--docs/configexamples/gcp-ha-vpn-bgp.md297
-rw-r--r--docs/configexamples/index.md1
-rw-r--r--docs/configuration/protocols/bgp.md2977
-rw-r--r--docs/configuration/service/lldp.md326
-rw-r--r--docs/configuration/system/ipv6.md469
-rw-r--r--docs/configuration/system/option.md85
-rw-r--r--docs/installation/virtual/docker.md77
-rw-r--r--docs/vpp/configuration/dataplane/cpu.md21
-rw-r--r--docs/vpp/configuration/dataplane/system.md55
-rw-r--r--docs/vpp/requirements.md32
16 files changed, 3655 insertions, 1024 deletions
diff --git a/docs/_static/css/version-picker.css b/docs/_static/css/version-picker.css
new file mode 100644
index 00000000..16ce16c3
--- /dev/null
+++ b/docs/_static/css/version-picker.css
@@ -0,0 +1,11 @@
+.vyos-version-picker-item { list-style: none; }
+#vyos-version-picker { display: flex; align-items: center; gap: .5em; padding: .4em 0; font-size: .9em; }
+#vyos-version-picker select { max-width: 14em; padding: .15em .3em; }
+#vyos-version-picker select:focus { outline: 2px solid #ffae12; outline-offset: 1px; }
+.vyos-pdf-link { font-weight: 600; }
+.vyos-version-banner { position: relative; padding: .6em 2.2em .6em 1em; font-size: .95em; line-height: 1.4; }
+.vyos-banner-dev { background: #e7f2fa; color: #2a6496; }
+.vyos-banner-newer-lts { background: #fff6e5; color: #6b5900; }
+.vyos-banner-eol { background: #fdecea; color: #8a1f11; }
+.vyos-version-banner a { text-decoration: underline; color: inherit; font-weight: 600; }
+.vyos-banner-dismiss { position: absolute; right: .5em; top: .35em; background: none; border: 0; font-size: 1.2em; cursor: pointer; color: inherit; }
diff --git a/docs/_static/js/pagefind-wrapper.js b/docs/_static/js/pagefind-wrapper.js
new file mode 100644
index 00000000..a4acadf8
--- /dev/null
+++ b/docs/_static/js/pagefind-wrapper.js
@@ -0,0 +1,69 @@
+/* Version-scoped Pagefind loader. Derives its base from the current URL so the
+ * same file works on production, canary, and /pr-<n>/ previews (§9). */
+(function (window) {
+ 'use strict';
+
+ function basePathFor(pathname) {
+ var m = pathname.match(/^((\/pr-\d+)?\/[a-z]{2}(?:_[A-Z]{2})?\/[^/]+\/)/);
+ if (!m) return null;
+ return { base: m[1], prefix: m[2] || '' };
+ }
+
+ function prefixResultUrl(url, prefix) {
+ return prefix ? prefix + url : url;
+ }
+
+ function assetUrlsFor(base) {
+ return {
+ css: base + 'pagefind/pagefind-ui.css',
+ js: base + 'pagefind/pagefind-ui.js',
+ };
+ }
+
+ function init() {
+ var mount = document.getElementById('vyos-search');
+ if (!mount) return;
+ var ctx = basePathFor(window.location.pathname);
+ if (!ctx) return;
+ var assets = assetUrlsFor(ctx.base);
+ /* Stylesheet first so the UI never renders unstyled. CSS load failure is
+ * cosmetic only — no error handler on the link. */
+ var l = document.createElement('link');
+ l.rel = 'stylesheet';
+ l.href = assets.css;
+ document.head.appendChild(l);
+ var s = document.createElement('script');
+ s.src = assets.js;
+ s.onerror = function () {
+ /* Per-version Pagefind assets missing (index not built yet, preview
+ * namespace, transient failure) — show a visible notice instead of
+ * leaving #vyos-search a silent empty div. */
+ var p = document.createElement('p');
+ p.className = 'vyos-search-unavailable';
+ p.textContent = 'Search is temporarily unavailable for this version.';
+ mount.appendChild(p);
+ };
+ s.onload = function () {
+ /* global PagefindUI */
+ new window.PagefindUI({
+ element: '#vyos-search',
+ baseUrl: ctx.base,
+ bundlePath: ctx.base + 'pagefind/',
+ processResult: function (result) {
+ result.url = prefixResultUrl(result.url, ctx.prefix);
+ return result;
+ },
+ });
+ };
+ document.head.appendChild(s);
+ }
+
+ window.VyOSSearch = {
+ basePathFor: basePathFor,
+ prefixResultUrl: prefixResultUrl,
+ assetUrlsFor: assetUrlsFor,
+ init: init,
+ };
+ if (typeof document !== 'undefined' && document.addEventListener)
+ document.addEventListener('DOMContentLoaded', init);
+})(window);
diff --git a/docs/_static/js/version-picker.js b/docs/_static/js/version-picker.js
new file mode 100644
index 00000000..84f68fd6
--- /dev/null
+++ b/docs/_static/js/version-picker.js
@@ -0,0 +1,193 @@
+/* VyOS docs version picker + status banner + language scaffold.
+ * Vanilla JS, no dependencies, no build step. Degrades silently when
+ * /versions.json is unreachable (docs stay fully readable). */
+(function (window) {
+ 'use strict';
+
+ // Deliberately does not match /pr-<n>/ preview prefixes — previews are single-version,
+ // so the picker has nothing to switch between and stays hidden there by design.
+ // The (?!\.\.?\/) guard rejects the dot-segments "." and ".." as slugs, which would
+ // otherwise escape the /<lang>/<slug>/ tree once the browser normalizes the URL.
+ function parseLocation(pathname) {
+ var m = pathname.match(/^\/([a-z]{2}(?:_[A-Z]{2})?)\/(?!\.\.?\/)([A-Za-z0-9._-]+)\/(.*)$/);
+ if (!m) return null;
+ return { lang: m[1], slug: m[2], rest: m[3] };
+ }
+
+ // Contract: versions.json lists versions newest-first, so the first 'lts' entry found
+ // here is the newest LTS — callers rely on that ordering rather than comparing versions.
+ function newestLts(manifest) {
+ for (var i = 0; i < manifest.versions.length; i++)
+ if (manifest.versions[i].status === 'lts') return manifest.versions[i].slug;
+ return null;
+ }
+
+ function bannerFor(slug, manifest) {
+ var entry = null, i;
+ for (i = 0; i < manifest.versions.length; i++)
+ if (manifest.versions[i].slug === slug) entry = manifest.versions[i];
+ if (!entry) return null;
+ var newest = newestLts(manifest);
+ if (entry.status === 'dev') return { kind: 'dev', newest: newest };
+ if (entry.status === 'eol') return { kind: 'eol', newest: newest };
+ if (entry.status === 'lts' && newest && newest !== slug)
+ return { kind: 'newer-lts', newest: newest };
+ return null;
+ }
+
+ /* Normalize one path segment: each well-formed %HH run is decoded and re-encoded on its
+ * own — per run, not per segment, so one malformed escape cannot double-encode the valid
+ * ones beside it (location.pathname hands escapes back verbatim, and blind re-encoding
+ * would turn %2E into %252E and miss on the HEAD probe). Literal spans, including a bare
+ * '%', always go through encodeURIComponent, so taint neutralization holds unconditionally;
+ * a run decoding to invalid UTF-8 is kept verbatim, being already pure %HH text.
+ * Decoding cannot resurrect a dot-segment: the URL parser resolves '.' / '..' and their
+ * percent-encoded forms during navigation, so pathname never presents them. */
+ function encodeSegment(seg) {
+ var out = '';
+ var re = /(?:%[0-9A-Fa-f]{2})+/g;
+ var last = 0;
+ var m;
+ while ((m = re.exec(seg))) {
+ out += encodeURIComponent(seg.slice(last, m.index));
+ try { out += encodeURIComponent(decodeURIComponent(m[0])); } catch (e) { out += m[0]; }
+ last = m.index + m[0].length;
+ }
+ return out + encodeURIComponent(seg.slice(last));
+ }
+
+ /* Percent-encode a multi-segment path one segment at a time, so the '/' separators
+ * survive. Real docs paths are plain ASCII sphinx slugs (letters/digits/-/_/./html),
+ * where this is a no-op — it exists to keep DOM-derived text (location.pathname,
+ * select.value) from reaching a location.href sink unescaped. */
+ function encodePath(rest) {
+ return rest.split('/').map(function (seg) { return encodeSegment(seg); }).join('/');
+ }
+
+ function targetUrlFor(loc, targetSlug) {
+ return '/' + encodeURIComponent(loc.lang) + '/' + encodeURIComponent(targetSlug) +
+ '/' + encodePath(loc.rest);
+ }
+
+ /* Full navigation URL for a version switch: same path on the target version
+ * with the current query string + fragment re-attached, so deep links
+ * (?highlight=…, #section) survive the switch (§4 URL-stability contract). */
+ function navUrlFor(loc, targetSlug, search, hash) {
+ return targetUrlFor(loc, targetSlug) + (search || '') + (hash || '');
+ }
+
+ /* Mirror of targetUrlFor for the language switch: swaps the lang segment while
+ * keeping the current version slug and path. */
+ function langUrlFor(loc, langCode) {
+ return '/' + encodeURIComponent(langCode) + '/' + encodeURIComponent(loc.slug) +
+ '/' + encodePath(loc.rest);
+ }
+
+ /* ---- DOM layer (no execution at import time) ---- */
+ function bannerText(b, manifest) {
+ if (b.kind === 'dev') return 'You are reading the development (rolling) docs.';
+ if (b.kind === 'eol') return 'This VyOS version is end-of-life; these docs are frozen. See the ' + b.newest + ' (LTS) docs.';
+ return 'A newer LTS (' + b.newest + ') is available.';
+ }
+
+ function init() {
+ var anchor = document.getElementById('vyos-version-picker');
+ if (!anchor) return;
+ var loc = parseLocation(window.location.pathname);
+ if (!loc) return;
+
+ fetch('/versions.json', { headers: { accept: 'application/json' } })
+ .then(function (r) { if (!r.ok) throw new Error('versions.json ' + r.status); return r.json(); })
+ .then(function (manifest) {
+ renderPicker(anchor, loc, manifest);
+ renderLang(anchor, loc, manifest);
+ renderBanner(loc, manifest);
+ })
+ .catch(function () { /* silent degradation (§4) */ });
+ }
+
+ function renderPicker(anchor, loc, manifest) {
+ var label = document.createElement('label');
+ label.setAttribute('for', 'vyos-version-select');
+ label.textContent = 'Version: ';
+ var sel = document.createElement('select');
+ sel.id = 'vyos-version-select';
+ manifest.versions.forEach(function (v) {
+ var o = document.createElement('option');
+ o.value = v.slug; o.textContent = v.label; o.selected = v.slug === loc.slug;
+ sel.appendChild(o);
+ });
+ sel.addEventListener('change', function () {
+ var search = window.location.search, hash = window.location.hash;
+ var target = navUrlFor(loc, sel.value, search, hash);
+ var fallback = '/' + encodeURIComponent(loc.lang) + '/' + encodeURIComponent(sel.value) +
+ '/' + (search || '') + (hash || '');
+ fetch(targetUrlFor(loc, sel.value), { method: 'HEAD' })
+ .then(function (r) {
+ window.location.href = (r.status === 404) ? fallback : target;
+ })
+ .catch(function () { window.location.href = fallback; });
+ });
+ anchor.appendChild(label);
+ anchor.appendChild(sel);
+
+ var entry = manifest.versions.filter(function (v) { return v.slug === loc.slug; })[0];
+ if (entry && entry.pdf) {
+ var a = document.createElement('a');
+ a.href = entry.pdf; a.className = 'vyos-pdf-link'; a.textContent = 'PDF';
+ anchor.appendChild(a);
+ }
+ }
+
+ function renderLang(anchor, loc, manifest) {
+ if (!manifest.languages || manifest.languages.length <= 1) return; // scaffold: hidden while en-only (§4)
+ var sel = document.createElement('select');
+ sel.id = 'vyos-lang-select';
+ sel.setAttribute('aria-label', 'Language');
+ manifest.languages.forEach(function (l) {
+ var o = document.createElement('option');
+ o.value = l.code; o.textContent = l.label; o.selected = l.code === loc.lang;
+ sel.appendChild(o);
+ });
+ sel.addEventListener('change', function () {
+ window.location.href = langUrlFor(loc, sel.value) +
+ window.location.search + window.location.hash;
+ });
+ anchor.appendChild(sel);
+ }
+
+ function renderBanner(loc, manifest) {
+ var b = bannerFor(loc.slug, manifest);
+ if (!b) return;
+ var key = 'vyos-banner-dismissed-' + loc.slug;
+ try { if (window.localStorage.getItem(key)) return; } catch (e) { /* private mode */ }
+ var div = document.createElement('div');
+ div.className = 'vyos-version-banner vyos-banner-' + b.kind;
+ div.setAttribute('role', b.kind === 'eol' ? 'alert' : 'note');
+ var span = document.createElement('span');
+ span.textContent = bannerText(b, manifest);
+ div.appendChild(span);
+ if (b.newest && b.kind !== 'dev') {
+ var link = document.createElement('a');
+ link.href = '/' + loc.lang + '/' + b.newest + '/';
+ link.textContent = ' Switch to ' + b.newest + '.';
+ div.appendChild(link);
+ }
+ var x = document.createElement('button');
+ x.textContent = '×'; x.className = 'vyos-banner-dismiss';
+ x.setAttribute('aria-label', 'Dismiss');
+ x.addEventListener('click', function () {
+ try { window.localStorage.setItem(key, '1'); } catch (e) { /* ignore */ }
+ div.remove();
+ });
+ div.appendChild(x);
+ document.body.insertBefore(div, document.body.firstChild);
+ }
+
+ window.VyOSVersionPicker = {
+ parseLocation: parseLocation, bannerFor: bannerFor, encodePath: encodePath,
+ targetUrlFor: targetUrlFor, navUrlFor: navUrlFor, langUrlFor: langUrlFor, init: init,
+ };
+ if (typeof document !== 'undefined' && document.addEventListener)
+ document.addEventListener('DOMContentLoaded', init);
+})(window);
diff --git a/docs/_templates/breadcrumbs.html b/docs/_templates/breadcrumbs.html
new file mode 100644
index 00000000..1df3c859
--- /dev/null
+++ b/docs/_templates/breadcrumbs.html
@@ -0,0 +1,5 @@
+{%- extends "sphinx_rtd_theme/breadcrumbs.html" %}
+{% block breadcrumbs_aside %}
+<li class="vyos-version-picker-item"><div id="vyos-version-picker" aria-label="Documentation version"></div></li>
+{{ super() }}
+{% endblock %}
diff --git a/docs/_templates/searchbox.html b/docs/_templates/searchbox.html
new file mode 100644
index 00000000..5fdd378f
--- /dev/null
+++ b/docs/_templates/searchbox.html
@@ -0,0 +1,13 @@
+{#- Full override (sphinx_rtd_theme/layout.html does a plain {% include "searchbox.html" %},
+ not a named block, so there is nothing to {% extends %} + {% block %} here). Only mounts
+ the Pagefind UI on CF-Workers builds (conf.py sets html_context['vyos_cf_build'] from
+ DOCS_VERSION_SLUG) — ReadTheDocs runs plain Sphinx with no Pagefind step, so the mount's
+ assets would 404 there. On RTD (and any other non-CF build) fall through to the theme's
+ stock server-side search form via Sphinx's "!" bang-prefix (forces resolution from the
+ theme, bypassing this override, per sphinx/jinja2glue.py). #}
+{% if vyos_cf_build %}
+<div id="vyos-search" role="search"></div>
+<noscript>{% include "!searchbox.html" %}</noscript>
+{% else %}
+{% include "!searchbox.html" %}
+{% endif %}
diff --git a/docs/conf.py b/docs/conf.py
index ece118e4..36075621 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -46,6 +46,18 @@ extensions = ['sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.ifconfig',
'sphinx.ext.graphviz',
+ # LaTeX-only: converts image formats the LaTeX/PDF builder can't
+ # embed natively (webp, svg, ...) to PNG at build time. The
+ # LaTeX builder's supported_image_types is ['application/pdf',
+ # 'image/png', 'image/jpeg'] — without this, unsupported
+ # images (nearly all of ours are .webp) are silently dropped
+ # from the PDF output. No effect on the HTML builder, which
+ # supports webp/svg natively in the browser; imgconverter
+ # only fires post-transforms when the active builder's
+ # supported_image_types doesn't already cover the source
+ # format. See `image_converter` below + docker/im-convert.sh
+ # for the conversion command this depends on.
+ 'sphinx.ext.imgconverter',
'notfound.extension',
'autosectionlabel',
'myst_parser',
@@ -55,6 +67,20 @@ extensions = ['sphinx.ext.intersphinx',
'sphinx_sitemap',
]
+# sphinx.ext.imgconverter: use a thin wrapper (docker/im-convert.sh, installed
+# on PATH as `im-convert`) instead of ImageMagick's `convert` directly.
+# Debian's `imagemagick` package is built --without-rsvg, so its built-in SVG
+# coder (a minimal libxml2-based renderer, not a librsvg wrapper) can't
+# rasterize SVGs that embed a base64 raster <image> element — common in
+# diagrams exported from draw.io/diagrams.net — and fails with "unable to
+# open image `image/png;base64,...'". The wrapper routes .svg sources to
+# `rsvg-convert` (from librsvg2-bin) directly and everything else (webp,
+# gif, pdf, ...) through ImageMagick's `convert` as usual. If `im-convert`
+# isn't on PATH (e.g. a build environment other than docker/Dockerfile),
+# imgconverter's own `is_available()` check logs a warning and skips
+# conversion rather than failing the build.
+image_converter = 'im-convert'
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -122,6 +148,27 @@ html_static_path = ['_static']
html_extra_path = ['_html_extra']
+# Version picker + status banner + language scaffold (docs/_static/js/version-picker.js,
+# docs/_static/css/version-picker.css). Appended rather than assigned in case a later
+# addition to this file defines these lists first. Registered unconditionally: it degrades
+# silently on ReadTheDocs (fetch of /versions.json fails there, so nothing renders).
+# globals().get(...) (not a bare `html_js_files` reference guarded by `'html_js_files' in
+# dir()`) avoids a static-analysis F821 (possibly-undefined name) while keeping the same
+# runtime behavior: append to an existing list if one was already defined, else start fresh.
+html_js_files = [*globals().get('html_js_files', []), 'js/version-picker.js']
+html_css_files = [*globals().get('html_css_files', []), 'css/version-picker.css']
+
+# CF-Workers builds inject DOCS_VERSION_SLUG (docs-build.yml); ReadTheDocs builds
+# (until sunset) run plain Sphinx with no Pagefind step, so the Pagefind wrapper
+# script + the searchbox.html override (docs/_templates/searchbox.html) must only
+# activate for CF builds — otherwise RTD visitors hit a 404ing search mount.
+_vyos_cf_build = bool(os.environ.get('DOCS_VERSION_SLUG'))
+if _vyos_cf_build:
+ html_js_files = [*html_js_files, 'js/pagefind-wrapper.js']
+
+# circinus keeps building on ReadTheDocs until RTD sunset and its CF slug is also
+# `1.5`, so the baseurl is identical under both builders — the rolling branch's
+# DOCS_VERSION_SLUG/READTHEDOCS_VERSION resolution block is deliberately not ported.
html_baseurl = 'https://docs.vyos.io/en/1.5/'
_rtd_version_type = os.environ.get('READTHEDOCS_VERSION_TYPE', '')
@@ -139,6 +186,7 @@ html_context = {
'conf_py_path': '/docs/',
'gtm_id': os.environ.get('GTM_ID', ''),
'cookiebot_id': os.environ.get('COOKIEBOT_ID', ''),
+ 'vyos_cf_build': _vyos_cf_build,
}
# sphinx-sitemap: baseurl already includes /en/1.5/, so skip lang+version
diff --git a/docs/configexamples/gcp-ha-vpn-bgp.md b/docs/configexamples/gcp-ha-vpn-bgp.md
new file mode 100644
index 00000000..40b49ce3
--- /dev/null
+++ b/docs/configexamples/gcp-ha-vpn-bgp.md
@@ -0,0 +1,297 @@
+---
+lastproofread: '2026-07-09'
+---
+
+(examples-gcp-ha-vpn-bgp)=
+
+# Route-Based Site-to-Site VPN to Google Cloud HA VPN
+
+This guide shows an example of a redundant route-based IKEv2 site-to-site
+VPN from two VyOS edge peers to Google Cloud HA VPN. The tunnels use VTI
+interfaces and BGP over link-local `/30` address ranges for dynamic routing.
+
+## Prerequisites
+
+- A Google Cloud HA VPN gateway with tunnels on both gateway interfaces.
+- A Cloud Router with BGP enabled.
+- An external VPN gateway resource in Google Cloud with two interfaces,
+ where each interface represents one VyOS edge peer.
+- Manual BGP IPv4 next-hop addresses from unique `/30` ranges inside
+ `169.254.0.0/16`.
+- Firewall policy that permits UDP 500, UDP 4500, and ESP from the two
+ HA VPN public IP addresses to the VyOS edge peers.
+
+## Example
+
+```{eval-rst}
++---------------------------------------+------------------------------+
+| WAN interface | eth0 |
++---------------------------------------+------------------------------+
+| Cloud prefix advertised by Google | 10.70.0.0/20 |
++---------------------------------------+------------------------------+
+| Edge prefix advertised by VyOS | 10.80.0.0/24 |
++---------------------------------------+------------------------------+
+| VyOS edge 1 public IP | 198.51.100.10 |
++---------------------------------------+------------------------------+
+| VyOS edge 2 public IP | 198.51.100.11 |
++---------------------------------------+------------------------------+
+| Google Cloud HA VPN interface 0 IP | 203.0.113.10 |
++---------------------------------------+------------------------------+
+| Google Cloud HA VPN interface 1 IP | 203.0.113.11 |
++---------------------------------------+------------------------------+
+| Tunnel 0 VyOS BGP IP | 169.254.10.1/30 |
++---------------------------------------+------------------------------+
+| Tunnel 0 Google Cloud BGP IP | 169.254.10.2/30 |
++---------------------------------------+------------------------------+
+| Tunnel 1 VyOS BGP IP | 169.254.10.5/30 |
++---------------------------------------+------------------------------+
+| Tunnel 1 Google Cloud BGP IP | 169.254.10.6/30 |
++---------------------------------------+------------------------------+
+| VyOS ASN | 65010 |
++---------------------------------------+------------------------------+
+| Google Cloud ASN | 64514 |
++---------------------------------------+------------------------------+
+| Tunnel 0 pre-shared key | example-gcp-ha-vpn-psk-0 |
++---------------------------------------+------------------------------+
+| Tunnel 1 pre-shared key | example-gcp-ha-vpn-psk-1 |
++---------------------------------------+------------------------------+
+```
+
+Use unique, high-entropy pre-shared keys in production. This example assumes
+that each VyOS public IP address is configured directly on the WAN interface.
+If a VyOS edge peer is behind one-to-one NAT, use the interface address for
+`local-address` and keep `authentication local-id` set to the public IP
+registered in Google Cloud.
+
+Both VyOS edge peers must be able to route the edge prefix they advertise.
+If only one peer can reach `10.80.0.0/24`, advertise a different prefix or
+adjust the export policy for the other peer.
+
+## Google Cloud configuration
+
+On the Google Cloud side, create an HA VPN gateway, a Cloud Router, an
+external VPN gateway resource that represents the two VyOS edge peers, and
+two VPN tunnels:
+
+- This example follows the topology for two separate peer VPN gateways,
+ each with one interface and one public IP address.
+- In Google Cloud, model those two peer gateways as one external VPN gateway
+ resource with two interfaces.
+- Tunnel 0 connects HA VPN interface 0 to VyOS edge 1.
+- Tunnel 1 connects HA VPN interface 1 to VyOS edge 2.
+- The Cloud Router interface for tunnel 0 uses `169.254.10.2/30` and peers
+ with `169.254.10.1`.
+- The Cloud Router interface for tunnel 1 uses `169.254.10.6/30` and peers
+ with `169.254.10.5`.
+- Both Cloud Router BGP peers use peer ASN `65010`.
+- Advertise `10.70.0.0/20` from Google Cloud.
+
+## VyOS edge 1 configuration
+
+- Configure IKE and ESP settings supported by Google Cloud:
+
+```none
+set vpn ipsec esp-group GCP-ESP lifetime '10800'
+set vpn ipsec esp-group GCP-ESP mode 'tunnel'
+set vpn ipsec esp-group GCP-ESP pfs 'dh-group14'
+set vpn ipsec esp-group GCP-ESP proposal 10 encryption 'aes256'
+set vpn ipsec esp-group GCP-ESP proposal 10 hash 'sha256'
+
+set vpn ipsec ike-group GCP-IKE dead-peer-detection action 'restart'
+set vpn ipsec ike-group GCP-IKE dead-peer-detection interval '30'
+set vpn ipsec ike-group GCP-IKE key-exchange 'ikev2'
+set vpn ipsec ike-group GCP-IKE lifetime '36000'
+set vpn ipsec ike-group GCP-IKE proposal 10 dh-group '14'
+set vpn ipsec ike-group GCP-IKE proposal 10 encryption 'aes256'
+set vpn ipsec ike-group GCP-IKE proposal 10 hash 'sha256'
+set vpn ipsec ike-group GCP-IKE proposal 10 prf 'prfsha256'
+```
+
+- Enable IPsec on the WAN interface:
+
+```none
+set vpn ipsec interface 'eth0'
+```
+
+- Disable IPsec route autoinstall because routing is handled by VTI and BGP:
+
+```none
+set vpn ipsec options disable-route-autoinstall
+```
+
+- Configure the VTI:
+
+```none
+set interfaces vti vti10 address '169.254.10.1/30'
+set interfaces vti vti10 description 'Google Cloud HA VPN tunnel 0'
+set interfaces vti vti10 ip adjust-mss '1350'
+```
+
+- Configure the VPN tunnel:
+
+```none
+set vpn ipsec authentication psk gcp-ha-vpn-0 id '198.51.100.10'
+set vpn ipsec authentication psk gcp-ha-vpn-0 id '203.0.113.10'
+set vpn ipsec authentication psk gcp-ha-vpn-0 secret 'example-gcp-ha-vpn-psk-0'
+set vpn ipsec site-to-site peer gcp-ha-vpn-0 authentication local-id '198.51.100.10'
+set vpn ipsec site-to-site peer gcp-ha-vpn-0 authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer gcp-ha-vpn-0 authentication remote-id '203.0.113.10'
+set vpn ipsec site-to-site peer gcp-ha-vpn-0 connection-type 'initiate'
+set vpn ipsec site-to-site peer gcp-ha-vpn-0 description 'Google Cloud HA VPN tunnel 0'
+set vpn ipsec site-to-site peer gcp-ha-vpn-0 ike-group 'GCP-IKE'
+set vpn ipsec site-to-site peer gcp-ha-vpn-0 local-address '198.51.100.10'
+set vpn ipsec site-to-site peer gcp-ha-vpn-0 remote-address '203.0.113.10'
+set vpn ipsec site-to-site peer gcp-ha-vpn-0 vti bind 'vti10'
+set vpn ipsec site-to-site peer gcp-ha-vpn-0 vti esp-group 'GCP-ESP'
+```
+
+- Add an interface route to reach the Google Cloud BGP peer:
+
+```none
+set protocols static route 169.254.10.2/32 interface vti10
+```
+
+- Configure BGP routing policy and the BGP session:
+
+```none
+set policy prefix-list GCP-IN rule 10 action 'permit'
+set policy prefix-list GCP-IN rule 10 prefix '10.70.0.0/20'
+set policy prefix-list GCP-OUT rule 10 action 'permit'
+set policy prefix-list GCP-OUT rule 10 prefix '10.80.0.0/24'
+
+set policy route-map GCP-IN rule 10 action 'permit'
+set policy route-map GCP-IN rule 10 match ip address prefix-list 'GCP-IN'
+set policy route-map GCP-IN rule 20 action 'deny'
+set policy route-map GCP-OUT rule 10 action 'permit'
+set policy route-map GCP-OUT rule 10 match ip address prefix-list 'GCP-OUT'
+set policy route-map GCP-OUT rule 20 action 'deny'
+
+set protocols bgp system-as '65010'
+set protocols bgp parameters router-id '10.80.0.11'
+set protocols bgp address-family ipv4-unicast network '10.80.0.0/24'
+set protocols bgp neighbor 169.254.10.2 remote-as '64514'
+set protocols bgp neighbor 169.254.10.2 address-family ipv4-unicast route-map import 'GCP-IN'
+set protocols bgp neighbor 169.254.10.2 address-family ipv4-unicast route-map export 'GCP-OUT'
+set protocols bgp neighbor 169.254.10.2 address-family ipv4-unicast soft-reconfiguration 'inbound'
+set protocols bgp neighbor 169.254.10.2 timers holdtime '30'
+set protocols bgp neighbor 169.254.10.2 timers keepalive '10'
+set protocols bgp neighbor 169.254.10.2 disable-connected-check
+```
+
+## VyOS edge 2 configuration
+
+- Configure IKE and ESP settings supported by Google Cloud:
+
+```none
+set vpn ipsec esp-group GCP-ESP lifetime '10800'
+set vpn ipsec esp-group GCP-ESP mode 'tunnel'
+set vpn ipsec esp-group GCP-ESP pfs 'dh-group14'
+set vpn ipsec esp-group GCP-ESP proposal 10 encryption 'aes256'
+set vpn ipsec esp-group GCP-ESP proposal 10 hash 'sha256'
+
+set vpn ipsec ike-group GCP-IKE dead-peer-detection action 'restart'
+set vpn ipsec ike-group GCP-IKE dead-peer-detection interval '30'
+set vpn ipsec ike-group GCP-IKE key-exchange 'ikev2'
+set vpn ipsec ike-group GCP-IKE lifetime '36000'
+set vpn ipsec ike-group GCP-IKE proposal 10 dh-group '14'
+set vpn ipsec ike-group GCP-IKE proposal 10 encryption 'aes256'
+set vpn ipsec ike-group GCP-IKE proposal 10 hash 'sha256'
+set vpn ipsec ike-group GCP-IKE proposal 10 prf 'prfsha256'
+```
+
+- Enable IPsec on the WAN interface:
+
+```none
+set vpn ipsec interface 'eth0'
+```
+
+- Disable IPsec route autoinstall because routing is handled by VTI and BGP:
+
+```none
+set vpn ipsec options disable-route-autoinstall
+```
+
+- Configure the VTI:
+
+```none
+set interfaces vti vti11 address '169.254.10.5/30'
+set interfaces vti vti11 description 'Google Cloud HA VPN tunnel 1'
+set interfaces vti vti11 ip adjust-mss '1350'
+```
+
+- Configure the VPN tunnel:
+
+```none
+set vpn ipsec authentication psk gcp-ha-vpn-1 id '198.51.100.11'
+set vpn ipsec authentication psk gcp-ha-vpn-1 id '203.0.113.11'
+set vpn ipsec authentication psk gcp-ha-vpn-1 secret 'example-gcp-ha-vpn-psk-1'
+set vpn ipsec site-to-site peer gcp-ha-vpn-1 authentication local-id '198.51.100.11'
+set vpn ipsec site-to-site peer gcp-ha-vpn-1 authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer gcp-ha-vpn-1 authentication remote-id '203.0.113.11'
+set vpn ipsec site-to-site peer gcp-ha-vpn-1 connection-type 'initiate'
+set vpn ipsec site-to-site peer gcp-ha-vpn-1 description 'Google Cloud HA VPN tunnel 1'
+set vpn ipsec site-to-site peer gcp-ha-vpn-1 ike-group 'GCP-IKE'
+set vpn ipsec site-to-site peer gcp-ha-vpn-1 local-address '198.51.100.11'
+set vpn ipsec site-to-site peer gcp-ha-vpn-1 remote-address '203.0.113.11'
+set vpn ipsec site-to-site peer gcp-ha-vpn-1 vti bind 'vti11'
+set vpn ipsec site-to-site peer gcp-ha-vpn-1 vti esp-group 'GCP-ESP'
+```
+
+- Add an interface route to reach the Google Cloud BGP peer:
+
+```none
+set protocols static route 169.254.10.6/32 interface vti11
+```
+
+- Configure BGP routing policy and the BGP session:
+
+```none
+set policy prefix-list GCP-IN rule 10 action 'permit'
+set policy prefix-list GCP-IN rule 10 prefix '10.70.0.0/20'
+set policy prefix-list GCP-OUT rule 10 action 'permit'
+set policy prefix-list GCP-OUT rule 10 prefix '10.80.0.0/24'
+
+set policy route-map GCP-IN rule 10 action 'permit'
+set policy route-map GCP-IN rule 10 match ip address prefix-list 'GCP-IN'
+set policy route-map GCP-IN rule 20 action 'deny'
+set policy route-map GCP-OUT rule 10 action 'permit'
+set policy route-map GCP-OUT rule 10 match ip address prefix-list 'GCP-OUT'
+set policy route-map GCP-OUT rule 20 action 'deny'
+
+set protocols bgp system-as '65010'
+set protocols bgp parameters router-id '10.80.0.12'
+set protocols bgp address-family ipv4-unicast network '10.80.0.0/24'
+set protocols bgp neighbor 169.254.10.6 remote-as '64514'
+set protocols bgp neighbor 169.254.10.6 address-family ipv4-unicast route-map import 'GCP-IN'
+set protocols bgp neighbor 169.254.10.6 address-family ipv4-unicast route-map export 'GCP-OUT'
+set protocols bgp neighbor 169.254.10.6 address-family ipv4-unicast soft-reconfiguration 'inbound'
+set protocols bgp neighbor 169.254.10.6 timers holdtime '30'
+set protocols bgp neighbor 169.254.10.6 timers keepalive '10'
+set protocols bgp neighbor 169.254.10.6 disable-connected-check
+```
+
+## Monitoring
+
+Use the following commands to verify the IPsec and BGP state on each VyOS
+edge peer:
+
+```none
+show vpn ike sa
+show vpn ipsec sa
+show ip bgp summary
+show ip route bgp
+```
+
+## References
+
+% stop_vyoslinter
+
+- [Google Cloud: create an HA VPN gateway to a peer VPN gateway]
+- [Google Cloud: HA VPN topologies]
+- [Google Cloud: supported IKE ciphers]
+
+[Google Cloud: create an HA VPN gateway to a peer VPN gateway]: https://docs.cloud.google.com/network-connectivity/docs/vpn/how-to/creating-ha-vpn
+[Google Cloud: HA VPN topologies]: https://docs.cloud.google.com/network-connectivity/docs/vpn/concepts/topologies
+[Google Cloud: supported IKE ciphers]: https://docs.cloud.google.com/network-connectivity/docs/vpn/concepts/supported-ike-ciphers
+
+% start_vyoslinter
diff --git a/docs/configexamples/index.md b/docs/configexamples/index.md
index e5a81305..b19020cd 100644
--- a/docs/configexamples/index.md
+++ b/docs/configexamples/index.md
@@ -12,6 +12,7 @@ bgp-ipv6-unnumbered
ospf-unnumbered
azure-vpn-bgp
azure-vpn-dual-bgp
+gcp-ha-vpn-bgp
ha
wan-load-balancing
pppoe-ipv6-basic
diff --git a/docs/configuration/protocols/bgp.md b/docs/configuration/protocols/bgp.md
index ebd5fdff..7204e63a 100644
--- a/docs/configuration/protocols/bgp.md
+++ b/docs/configuration/protocols/bgp.md
@@ -1,1408 +1,2810 @@
-(routing-bgp)=
+---
+myst:
+ html_meta:
+ description: |
+ BGP is the path-vector exterior gateway protocol used to exchange
+ routing and reachability information between autonomous systems on
+ the internet.
+ keywords: bgp, ebgp, ibgp, asn, route-reflector, confederation, peer-group
+---
+
+(bgp)=
# BGP
-{abbr}`BGP (Border Gateway Protocol)` is one of the Exterior Gateway Protocols
-and the de facto standard interdomain routing protocol. The latest BGP version
-is 4. BGP-4 is described in {rfc}`1771` and updated by {rfc}`4271`. {rfc}`2858`
-adds multiprotocol support to BGP.
+Border Gateway Protocol (BGP) is the path-vector exterior gateway protocol
+used to exchange routing and reachability information between
+{abbr}`ASs (Autonomous Systems)` on the Internet. BGP-4, the current
+version, is specified in
+[RFC 4271](https://datatracker.ietf.org/doc/html/rfc4271). Multiprotocol
+extensions to BGP, which allow it to carry routing information for address
+families beyond IPv4 unicast, are defined in
+[RFC 4760](https://datatracker.ietf.org/doc/html/rfc4760).
+
+
+## Basic concepts
+
+### Autonomous systems
+
+An {abbr}`AS (Autonomous System)` is a connected group of IP prefixes
+managed by one or more network operators under a single, clearly defined
+routing policy
+([RFC 1930](https://datatracker.ietf.org/doc/html/rfc1930)).
+
+Every AS is identified by an {abbr}`ASN (Autonomous System Number)`. ASNs
+were originally two-byte values (1-65535), with the range 64512-65534
+reserved for private use
+([RFC 6996](https://datatracker.ietf.org/doc/html/rfc6996)) and prohibited
+on the global Internet. The two-byte pool has since been exhausted, so
+regional Internet registries now allocate four-byte ASNs (1-4,294,967,295) by
+default, as defined in
+[RFC 6793](https://datatracker.ietf.org/doc/html/rfc6793).
+
+ASNs are essential elements of BGP. As a path-vector protocol, BGP records
+the chain of ASNs a route has crossed in the AS_PATH attribute and uses
+that chain both as a metric in best path selection (shorter AS_PATH wins,
+other criteria being equal) and as a loop-detection mechanism.
+
+### Address families
+
+Multiprotocol BGP extensions enable BGP to carry routing information for
+multiple network-layer protocols. Each address family is identified by an
+{abbr}`AFI (Address Family Identifier)`/
+{abbr}`SAFI (Subsequent Address Family Identifier)`
+pair: the AFI names the network-layer protocol (IPv4, IPv6, etc.), and the
+SAFI names the route type (unicast, multicast, MPLS-labeled, VPN, etc.).
+
+VyOS supports IPv4 and IPv6 unicast, multicast, labeled unicast, VPN
+(MPLS L3VPN), and flowspec address families, plus the L2VPN-EVPN and
+BGP Link-State families. This document covers configuration of the IPv4
+and IPv6 unicast address families, which are the most common in
+inter-domain routing.
+
+### Route selection
+
+FRR's BGP implementation selects routes by applying the following decision
+criteria, in order from top to bottom, until one is applicable.
+
+1. **Weight check:** Prefer the route with the higher local weight.
+2. **Local preference check:** Prefer the route with the higher
+ LOCAL_PREF.
+3. **Local route check:** Prefer locally originated routes (statics,
+ aggregates, redistributed) over received routes.
+4. **AS path length check:** Prefer the route with the shortest AS_PATH
+ length.
+5. **Origin check:** Prefer the route with the lowest origin type
+ (IGP < EGP < Incomplete).
+6. **MED check:** When multiple routes are received from the same
+ neighboring AS, prefer the route with the lowest
+ {abbr}`MED (Multi-Exit Discriminator)` value.
+7. **External check:** Prefer the route received from an external (eBGP)
+ peer over routes received from other types of peers.
+8. **IGP cost check:** Prefer the route with the lower IGP cost to the
+ next hop.
+9. **Multi-path check:** If multi-path routing is enabled, check whether the
+ routes not yet distinguished in preference may be considered equal. If
+ `bestpath as-path multipath-relax` is set, all such routes are
+ considered equal; otherwise, routes received via iBGP with identical
+ AS_PATHs, or routes received from eBGP neighbors in the same AS, are
+ considered equal.
+10. **Already-selected external check:** When both routes are received
+ from eBGP peers, prefer the route that was already selected. This
+ check is skipped if `bestpath compare-routerid` is configured. It can
+ prevent some cases of route oscillation.
+11. **Router ID check:** Prefer the route with the lowest router ID. If
+ the route has an ORIGINATOR_ID attribute (set during iBGP
+ reflection), that value is used; otherwise, the router ID of the peer
+ the route was received from is used.
+12. **Cluster list length check:** Prefer the route with the shortest
+ CLUSTER_LIST length. The cluster list reflects the iBGP reflection
+ path the route has taken.
+13. **Peer address:** Prefer the route received from the peer with the
+ lowest transport-layer IP address, as a last-resort tie-breaker.
+
+### Capability advertisement
+
+BGP-4 originally had no mechanism for a speaker to advertise which optional
+protocol features it supports. Capability advertisement, defined in
+[RFC 5492](https://datatracker.ietf.org/doc/html/rfc5492), addresses this
+by allowing each BGP speaker to list its supported capabilities in the
+OPEN message. Capabilities cover features such as multiprotocol
+extensions, route refresh, 4-byte ASN support, graceful restart, and
+ADD-PATH.
+
+By default, a BGP implementation brings up a peering with the minimal
+capabilities that are common to both sides. For example, if the local
+router supports both unicast and multicast and the remote router
+supports only unicast, the session is established with unicast
+capability only. When the two sides share no common capabilities, one
+side sends an Unsupported Capability error and terminates the session.
+
+If a peer is configured exclusively as an IPv4 unicast neighbor and no
+other optional features require capability negotiation, VyOS' BGP
+implementation does not send any capability advertisements.
-VyOS makes use of {abbr}`FRR (Free Range Routing)` and we would like to thank
-them for their effort!
+## Configuration
+
+### Local BGP router configuration
+
+Configure the local BGP router with its ASN. The BGP process uses the ASN
+to determine if a session is internal (iBGP) or external (eBGP).
+
+```{cfgcmd} set protocols bgp system-as \<1-4294967294\>
+
+**Configure the Autonomous System Number (ASN) for the local BGP router.**
+
+This setting is mandatory. ASN 0 and ASN 4294967295 are reserved
+([RFC 7607](https://datatracker.ietf.org/doc/html/rfc7607),
+[RFC 7300](https://datatracker.ietf.org/doc/html/rfc7300)) and cannot be
+configured.
+```
-## Basic Concepts
+Example:
-(bgp-autonomous-systems)=
+```none
+set protocols bgp system-as 64512
+```
-### Autonomous Systems
+### Peer configuration
-From {rfc}`1930`:
+#### Defining peers
-> An AS is a connected group of one or more IP prefixes run by one or more
-> network operators which has a SINGLE and CLEARLY DEFINED routing policy.
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> remote-as \<1-4294967294 | auto | external | internal\>
-Each {abbr}`AS (Autonomous System)` has an identifying number associated with it
-called an {abbr}`ASN (Autonomous System Number)`. This is a two octet value
-ranging in value from 1 to 65535. The AS numbers 64512 through 65535 are defined
-as private AS numbers. Private AS numbers must not be advertised on the global
-Internet. The 2-byte AS number range has been exhausted. 4-byte AS numbers are
-specified in {rfc}`6793`, and provide a pool of 4294967296 AS numbers.
+**Configure the ASN of the specified BGP neighbor.**
-The {abbr}`ASN (Autonomous System Number)` is one of the essential elements of
-BGP. BGP is a distance vector routing protocol, and the AS-Path framework
-provides distance vector metric and loop detection to BGP.
+The neighbor identity can be an IPv4 address, an IPv6 address (including a
+link-local address), or an interface name for unnumbered peering.
-```{cfgcmd} set protocols bgp system-as \<asn\>
+The ASN can be configured as:
-Set local {abbr}`ASN (Autonomous System Number)` that this router represents.
-This is a a mandatory option!
+- An explicit number in the range 1 to 4294967294.
+- `auto`: automatically detect the neighbor's ASN from the OPEN
+ message.
+- `external`: reject the connection if the peer's ASN matches the
+ local AS (eBGP session).
+- `internal`: reject the connection if the peer's ASN differs from
+ the local AS (iBGP session).
```
-(bgp-address-families)=
+Example:
+```none
+set protocols bgp neighbor 192.0.2.2 remote-as 64513
+```
-### Address Families
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> remote-as internal
+**Configure the specified neighbor as an iBGP peer.**
-Multiprotocol extensions enable BGP to carry routing information for multiple
-network layer protocols. BGP supports an Address Family Identifier (AFI) for
-IPv4 and IPv6.
+The peer's AS number must match the locally configured `system-as`. If it
+does not, the BGP peering session with this neighbor is rejected.
+```
+Example:
-(bgp-route-selection)=
+```none
+set protocols bgp neighbor 192.0.2.2 remote-as internal
+```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> remote-as external
-### Route Selection
+**Configure the specified neighbor as an eBGP peer.**
+The peer's AS number must differ from the locally configured `system-as`.
+If it matches, the BGP peering session with this neighbor is rejected.
+```
-The route selection process used by FRR's BGP implementation uses the following
-decision criterion, starting at the top of the list and going towards the
-bottom until one of the factors can be used.
+Example:
+```none
+set protocols bgp neighbor 192.0.2.2 remote-as external
+```
-01. **Weight check**
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> remote-as auto
+**Configure a BGP neighbor whose ASN is learned from the OPEN message
+this neighbor sends at session setup.**
+```
- Prefer higher local weight routes to lower routes.
+Example:
+```none
+set protocols bgp neighbor 192.0.2.2 remote-as auto
+```
-02. **Local preference check**
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> port \<1-65535\>
+**Configure the TCP destination port used when initiating the BGP session
+with the specified peer.**
- Prefer higher local preference routes to lower.
+By default, BGP uses TCP port 179 (IANA-assigned).
+```
+Example:
-03. **Local route check**
+```none
+set protocols bgp neighbor 192.0.2.2 port 1179
+```
+```{cfgcmd} set protocols bgp neighbor \<interface\> interface source-interface \<interface\>
- Prefer local routes (statics, aggregates, redistributed) to received routes.
+**Configure the local source interface used for the unnumbered BGP
+session.**
+```
+```{note}
+This command applies only when the neighbor is specified by interface
+name (unnumbered peering).
+```
-04. **AS path length check**
+Example:
+```none
+set protocols bgp neighbor eth1 interface source-interface eth1
+```
- Prefer shortest hop-count AS_PATHs.
+```{cfgcmd} set protocols bgp neighbor \<interface\> interface v6only remote-as \<1-4294967294 | auto | external | internal\>
+**Configure an IPv6 link-local-only unnumbered peering on the specified
+interface and set the neighbor's ASN.**
-05. **Origin check**
+With `v6only`, the BGP session is established over the IPv6 link-local
+address of the interface without requiring any globally routable
+address on either side.
+The ASN can be configured as:
- Prefer the lowest origin type route. That is, prefer IGP origin routes to
- EGP, to Incomplete routes.
+- An explicit number in the range 1 to 4294967294.
+- `auto`: automatically detect the neighbor's ASN from the OPEN
+ message.
+- `external`: Any non-local ASN, treated as eBGP.
+- `internal`: The same ASN as the local router, treated as iBGP.
+```
+Example:
-06. **MED check**
+```none
+set protocols bgp neighbor eth1 interface v6only remote-as external
+```
+```{cfgcmd} set protocols bgp neighbor \<interface\> interface v6only peer-group \<name\>
- Where routes with a MED were received from the same AS, prefer the route
- with the lowest MED.
+**Assign an IPv6-link-local-only unnumbered peering on the specified
+interface to a peer group.**
+The unnumbered peering inherits all parameters from the peer group.
+```
-07. **External check**
+```{note}
+The peer group must already be configured.
+```
+Example:
- Prefer the route received from an external, eBGP peer over routes received
- from other types of peers.
+```none
+set protocols bgp neighbor eth1 interface v6only peer-group FABRIC
+```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> local-role \<customer | peer | provider | rs-client | rs-server\> [strict]
-08. **IGP cost check**
+**Configure the local BGP role for the session
+([RFC 9234](https://datatracker.ietf.org/doc/html/rfc9234)).**
+Each side advertises its role via the BGP Role capability, and the
+following two roles form a valid pairing:
- Prefer the route with the lower IGP cost.
+- Provider <-> Customer
+- RS-Server <-> RS-Client
+- Peer <-> Peer
+If the roles do not pair correctly, the session is rejected with a Role
+Mismatch notification.
-09. **Multi-path check**
+When `strict` is set, the session requires the neighbor to advertise its
+role. If the neighbor does not include the BGP Role capability, the
+session is rejected. Enable this option when you want to be sure the
+other side is also role-configured.
+Once the local role is set, the BGP daemon automatically applies the
+{abbr}`OTC (Only-to-Customer)` attribute to detect and prevent route
+leaks:
- If multi-pathing is enabled, then check whether the routes not yet
- distinguished in preference may be considered equal. If
- {cfgcmd}`bgp bestpath as-path multipath-relax` is set, all such routes are
- considered equal, otherwise routes received via iBGP with identical AS_PATHs
- or routes received from eBGP neighbours in the same AS are considered equal.
+- Routes sent to a Customer, RS-Client, or Peer are tagged with OTC.
+- Routes already carrying OTC are not sent back up to a Provider,
+ RS-Server, or Peer.
+- Between two peers, a received route with OTC is accepted only if the
+ OTC value equals the peer's ASN.
+- Routes received from a Customer or RS-Client that already carry OTC are
+ treated as route leaks and rejected.
+No extra policy configuration is needed; the rules apply automatically.
+```
-10. **Already-selected external check**
+Example:
+```none
+set protocols bgp neighbor 192.0.2.2 local-role customer strict
+```
- Where both routes were received from eBGP peers, then prefer the route
- which is already selected. Note that this check is not applied if
- {cfgcmd}`bgp bestpath compare-routerid` is configured. This check can
- prevent some cases of oscillation.
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> shutdown
+**Administratively disable the BGP session with the specified peer.**
-11. **Router-ID check**
+To re-enable the session, use the `delete` form of this command.
+```
+Example:
- Prefer the route with the lowest router-ID. If the route has an
- ORIGINATOR_ID attribute, through iBGP reflection, then that router ID is
- used, otherwise the router-ID of the peer the route was received from is
- used.
+```none
+set protocols bgp neighbor 192.0.2.2 shutdown
+```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> description \<text\>
-12. **Cluster-List length check**
+**Configure a free-form description for the specified peer.**
+The description may be up to 255 characters.
+```
- The route with the shortest cluster-list length is used. The cluster-list
- reflects the iBGP reflection path the route has taken.
+Example:
+```none
+set protocols bgp neighbor 192.0.2.2 description 'Upstream provider'
+```
-13. **Peer address**
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> update-source \<address | interface\>
+**Configure the source IP address used by the local BGP speaker when
+opening the TCP connection to the specified neighbor.**
- Prefer the route received from the peer with the higher transport layer
- address, as a last-resort tie-breaker.
+The source IP address can be specified either as an IP address or as an
+interface name.
+```
+Example:
-(bgp-capability-negotiation)=
+```none
+set protocols bgp neighbor 192.0.2.2 update-source 192.0.2.1
+```
+#### Capability negotiation
-### Capability Negotiation
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> capability dynamic
+**Enable Dynamic Capability negotiation with the specified peer.**
-When adding IPv6 routing information exchange feature to BGP. There were some
-proposals. {abbr}`IETF (Internet Engineering Task Force)`
-{abbr}`IDR (Inter Domain Routing)` adopted a proposal called Multiprotocol
-Extension for BGP. The specification is described in {rfc}`2283`. The protocol
-does not define new protocols. It defines new attributes to existing BGP. When
-it is used exchanging IPv6 routing information it is called BGP-4+. When it is
-used for exchanging multicast routing information it is called MBGP.
+This enables updating active capabilities during an established BGP
+session without resetting the session.
+```
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 capability dynamic
+```
-*bgpd* supports Multiprotocol Extension for BGP. So if a remote peer supports
-the protocol, *bgpd* can exchange IPv6 and/or multicast routing information.
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> capability extended-nexthop
+**Enable the Extended Next Hop capability
+([RFC 8950](https://datatracker.ietf.org/doc/html/rfc8950)) negotiation
+with the specified peer.**
-Traditional BGP did not have the feature to detect a remote peer's
-capabilities, e.g. whether it can handle prefix types other than IPv4 unicast
-routes. This was a big problem using Multiprotocol Extension for BGP in an
-operational network. {rfc}`2842` adopted a feature called Capability
-Negotiation. *bgpd* use this Capability Negotiation to detect the remote peer's
-capabilities. If a peer is only configured as an IPv4 unicast neighbor, *bgpd*
-does not send these Capability Negotiation packets (at least not unless other
-optional BGP features require capability negotiation).
+When the BGP session runs over an IPv6 link-local address, this capability
+is enabled automatically. When the session runs over an IPv6 global
+address, enabling this capability allows BGP to install IPv4 routes with
+IPv6 next hops, which is useful when no IPv4 addresses are configured on
+the transit interfaces.
+```
+Example:
-By default, FRR will bring up peering with minimal common capability for the
-both sides. For example, if the local router has unicast and multicast
-capabilities and the remote router only has unicast capability the local router
-will establish the connection with unicast only capability. When there are no
-common capabilities, FRR sends Unsupported Capability error and then resets the
-connection.
+```none
+set protocols bgp neighbor 2001:db8::2 capability extended-nexthop
+```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> capability software-version
-## Configuration
+**Configure BGP to advertise the Software Version capability to the
+specified peer.**
+This causes the local router to include the name and version of the
+software that implements BGP in the OPEN message. It is sent for
+purely informational purposes and does not affect BGP behavior.
+```
-(bgp-router-configuration)=
+Example:
+```none
+set protocols bgp neighbor 192.0.2.2 capability software-version
+```
-### BGP Router Configuration
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> disable-capability-negotiation
+**Suppress sending capability advertisements as OPEN message optional
+parameters to the specified peer.**
-First of all you must configure BGP router with the {abbr}`ASN (Autonomous
-System Number)`. The AS number is an identifier for the autonomous system.
-The BGP protocol uses the AS number for detecting whether the BGP connection
-is internal or external. VyOS does not have a special command to start the BGP
-process. The BGP process starts when the first neighbor is configured.
+The session is established using only the basic BGP-4 feature set, as if
+capabilities had never been introduced.
+```
-```{cfgcmd} set protocols bgp system-as \<asn\>
+```{note}
+To use the locally configured capabilities regardless of what the peer
+advertises, use `override-capability` instead.
+```
-Set local autonomous system number that this router represents. This is a
-mandatory option!
+```{note}
+Suppressing capability negotiation disables every BGP feature that
+depends on capability exchange, including BGP unnumbered, hostname
+support, 4-byte ASNs, ADD-PATH, Route Refresh, ORF, Dynamic Capabilities,
+and Graceful Restart. Use this option only when interoperating with a
+peer that cannot accept capabilities.
```
-#### Peers Configuration
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 disable-capability-negotiation
+```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> override-capability
-##### Defining Peers
+**Configure the session with the specified peer to use the locally
+configured capabilities, ignoring capabilities advertised by the peer.**
+```
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> remote-as \<asn\>
+Example:
-This command creates a new neighbor whose remote-as is \<asn\>. The neighbor
-address can be an IPv4 address or an IPv6 address or an interface to use
-for the connection. The command is applicable for peer and peer group.
+```none
+set protocols bgp neighbor 192.0.2.2 override-capability
```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> strict-capability-match
+
+**Configure the session with the specified peer to require an exact
+match between the local and remote capability sets.**
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> remote-as internal
+If the two sets differ, the router sends an Unsupported Capability
+notification and resets the connection.
-Create a peer as you would when you specify an ASN, except that if the
-peers ASN is different than mine as specified under the {cfgcmd}`protocols
-bgp <asn>` command the connection will be denied.
+If the peer does not implement capability advertisement at all, use
+`disable-capability-negotiation` to suppress local advertisement.
```
+Example:
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> remote-as external
+```none
+set protocols bgp neighbor 192.0.2.2 strict-capability-match
+```
+
+#### Peer parameters
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> allowas-in number \<1-10\>
-Create a peer as you would when you specify an ASN, except that if the
-peers ASN is the same as mine as specified under the {cfgcmd}`protocols
-bgp <asn>` command the connection will be denied.
+**Configure the session with the specified peer to accept incoming routes
+whose AS_PATH contains the local AS, up to the given number of
+occurrences.**
+
+This is useful when the same ASN is reused across multiple sites that
+cannot be connected directly. The `number` parameter (1-10) sets the
+maximum allowed occurrences of the local AS in the AS_PATH.
```
+```{note}
+This option applies only to eBGP peers and cannot be applied to peer
+groups.
+```
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> remote-as auto
+Example:
-Create a peer as you would when you specify an ASN, except that the peers
-remote ASN is detected automatically from the OPEN message.
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast allowas-in number 2
```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> as-override
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> local-role \<role\> [strict]
+**Configure the session with the specified peer to replace the peer's
+ASN in the AS_PATH of advertised routes with the local ASN.**
-BGP roles are defined in RFC {rfc}`9234` and provide an easy way to
-add route leak prevention, detection and mitigation. The local Role
-value is negotiated with the new BGP Role capability which has a
-built-in check of the corresponding value. In case of a mismatch the
-new OPEN Roles Mismatch Notification <2, 11> would be sent.
-The correct Role pairs are:
+This is typically used on a {abbr}`PE (Provider Edge)` router to replace
+the incoming customer ASN in advertisements to a connected
+{abbr}`CE (Customer Edge)`, so customers can reuse the same ASN across
+all their sites.
+```
-Provider - Customer
+```{note}
+This option applies only to eBGP peers.
+```
-Peer - Peer
+Example:
-RS-Server - RS-Client
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast as-override
+```
-If {cfgcmd}`strict` is set the BGP session won’t become established
-until the BGP neighbor sets local Role on its side. This
-configuration parameter is defined in RFC {rfc}`9234` and is used to
-enforce the corresponding configuration at your counter-parts side.
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> attribute-unchanged \<as-path | med | next-hop\>
-Routes that are sent from provider, rs-server, or the peer local-role
-(or if received by customer, rs-client, or the peer local-role) will
-be marked with a new Only to Customer (OTC) attribute.
+**Configure BGP to advertise the specified path attribute (`as-path`,
+`med`, or `next-hop`) to the peer or peer group unchanged.**
+```
-Routes with this attribute can only be sent to your neighbor if your
-local-role is provider or rs-server. Routes with this attribute can
-be received only if your local-role is customer or rs-client.
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast attribute-unchanged next-hop
+```
-In case of peer-peer relationship routes can be received only if OTC
-value is equal to your neighbor AS number.
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> maximum-prefix \<1-4294967295\>
-All these rules with OTC will help to detect and mitigate route leaks
-and happen automatically if local-role is set.
+**Configure the maximum number of prefixes that the local BGP speaker
+will accept from the specified peer.**
+
+If the number of received prefixes exceeds this limit, the BGP session is
+torn down.
```
+Example:
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> shutdown
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast maximum-prefix 1000
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> nexthop-self
+
+**Configure the local BGP speaker to advertise itself as the NEXT_HOP
+for all routes advertised to the specified peer.**
-This command disable the peer or peer group. To reenable the peer use
-the delete form of this command.
+By default, the local speaker rewrites NEXT_HOP to its own IP address
+only when advertising to an eBGP peer and preserves the received NEXT_HOP
+when advertising to an iBGP peer. This option overrides the iBGP default.
```
+Example:
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> description \<text\>
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast nexthop-self
+```
-Set description of the peer or peer group.
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> nexthop-self force
+
+**Force the local route reflector to set itself as the NEXT_HOP on
+routes reflected to its route-reflector clients.**
+
+By default, a route reflector preserves the NEXT_HOP of reflected
+routes. This option overrides that behavior for the specified peer,
+which must be configured as a route-reflector client for the option to
+take effect.
+```
+
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast nexthop-self force
```
+<!--
+`nexthop-local unchanged` does not work as expected on the live VyOS
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family ipv6-unicast nexthop-local unchanged
+-->
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> remove-private-as
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> update-source \<address|interface\>
+**Configure the local BGP speaker to strip private ASNs from the AS_PATH
+of routes advertised to the specified eBGP peer.**
-Specify the IPv4 source address to use for the BGP session to this neighbor,
-may be specified as either an IPv4 address directly or as an interface name.
+Private ASNs are removed only if the AS_PATH consists entirely of
+private ASNs. If any public ASN is present in the path, no private ASN
+is removed.
```
-(bgp-capability-negotiation-1)=
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast remove-private-as
+```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> remove-private-as all
-##### Capability Negotiation
+**Configure the local BGP speaker to strip all private ASNs from the
+AS_PATH of routes advertised to the specified eBGP peer.**
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> capability dynamic
+Unlike `remove-private-as` without `all`, this option removes private
+ASNs unconditionally — even when public ASNs are also present in the
+path.
+```
+
+Example:
-This command would allow the dynamic update of capabilities over an
-established BGP session.
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast remove-private-as all
```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> soft-reconfiguration inbound
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> capability extended-nexthop
+**Enable inbound soft reconfiguration for the specified peer and address
+family.**
-Allow bgp to negotiate the extended-nexthop capability with it’s peer.
-If you are peering over a IPv6 Link-Local address then this capability
-is turned on automatically. If you are peering over a IPv6 Global Address
-then turning on this command will allow BGP to install IPv4 routes with
-IPv6 nexthops if you do not have IPv4 configured on interfaces.
+When enabled, the router stores incoming updates from the peer unmodified
+before any inbound policy is applied. If the inbound policy is changed,
+the stored updates are reprocessed locally to produce a new inbound
+state, so the session does not need to be cleared to apply policy
+changes.
```
+```{note}
+Storing updates requires memory, and enabling inbound soft
+reconfiguration for multiple neighbors can significantly increase memory
+usage.
+```
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> disable-capability-negotiation
+Example:
-Suppress sending Capability Negotiation as OPEN message optional
-parameter to the peer. This command only affects the peer is
-configured other than IPv4 unicast configuration.
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast soft-reconfiguration inbound
+```
-When remote peer does not have capability negotiation feature,
-remote peer will not send any capabilities at all. In that case,
-bgp configures the peer with configured capabilities.
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> weight \<1-65535\>
-You may prefer locally configured capabilities more than the negotiated
-capabilities even though remote peer sends capabilities. If the peer is
-configured by {cfgcmd}`override-capability`, VyOS ignores received
-capabilities then override negotiated capabilities with configured values.
+**Configure the default weight applied to routes received from the
+specified peer.**
-Additionally you should keep in mind that this feature fundamentally
-disables the ability to use widely deployed BGP features. BGP unnumbered,
-hostname support, AS4, Addpath, Route Refresh, ORF, Dynamic Capabilities,
-and graceful restart.
+Weight is a purely local attribute. It is never carried in BGP messages and is not
+advertised to other peers. Among the best path decision criteria, it is
+considered before everything else, and the highest weight wins.
```
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast weight 100
+```
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> override-capability
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> advertisement-interval \<0-600\>
-This command allow override the result of Capability Negotiation with
-local configuration. Ignore remote peer’s capability value.
+**Configure the minimum interval, in seconds, between successive route
+advertisements sent to the specified peer for the same destination.**
```
+Example:
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> strict-capability-match
+```none
+set protocols bgp neighbor 192.0.2.2 advertisement-interval 5
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> disable-connected-check
-This command forces strictly compare remote capabilities and local
-capabilities. If capabilities are different, send Unsupported Capability
-error then reset connection.
+**Allow eBGP sessions to establish regardless of the number of hops
+between peers.**
-You may want to disable sending Capability Negotiation OPEN message
-optional parameter to the peer when remote peer does not implement
-Capability Negotiation. Please use {cfgcmd}`disable-capability-negotiation`
-command to disable the feature.
+By default, eBGP packets are sent with a TTL of 1, which precludes
+sourcing from a non-connected address. This
+option bypasses the check.
```
-##### Peer Parameters
+Example:
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> allowas-in number \<number\>
+```none
+set protocols bgp neighbor 192.0.2.2 disable-connected-check
+```
-This command accept incoming routes with AS path containing AS
-number with the same value as the current system AS. This is
-used when you want to use the same AS number in your sites,
-but you can’t connect them directly.
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> disable-send-community \<extended | standard\>
- The number parameter (1-10) configures the amount of accepted
- occurrences of the system AS number in AS path.
+**Disable sending the specified community attributes to the peer.**
- This command is only allowed for eBGP peers. It is not applicable
- for peer groups.
+By default, both standard and extended community attributes are sent.
```
+Example:
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> as-override
+```none
+set protocols bgp neighbor 192.0.2.1 address-family ipv4-unicast disable-send-community standard
+```
-This command override AS number of the originating router with
-the local AS number.
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> ebgp-multihop \<1-255\>
-Usually this configuration is used in PEs (Provider Edge) to
-replace the incoming customer AS number so the connected CE (
-Customer Edge) can use the same AS number as the other customer
-sites. This allows customers of the provider network to use the
-same AS number across their sites.
+**Allow an eBGP session with a peer that is not directly connected by
+raising the TTL of outbound BGP packets to the specified value.**
-This command is only allowed for eBGP peers.
+By default, eBGP packets are sent with TTL 1, so a peer more than one hop
+away is unreachable unless this option is set. Accepted values are
+1-255, where 1 is equivalent to the default (single-hop) behavior.
```
+```{note}
+This command is mutually exclusive with `ttl-security hops`.
+```
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> attribute-unchanged \<as-path|med|next-hop\>
+Example:
-This command specifies attributes to be left unchanged for
-advertisements sent to a peer or peer group.
+```none
+set protocols bgp neighbor 192.0.2.2 ebgp-multihop 5
```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> local-as \<1-4294967294\> [no-prepend [replace-as]]
+
+**Configure an alternate local ASN for the BGP session with the specified
+peer. This command applies only to eBGP peers.**
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> maximum-prefix \<number\>
+Without modifiers, the `local-as` is prepended to the received AS_PATH
+when receiving updates from the peer, and to the outgoing AS_PATH (on
+top of the router's real ASN) when sending routes to the peer.
-This command specifies a maximum number of prefixes we can receive
-from a given peer. If this number is exceeded, the BGP session
-will be destroyed. The number range is 1 to 4294967295.
+With `no-prepend`, the `local-as` is not prepended to the AS_PATH of
+incoming updates from the peer.
+
+With `replace-as`, only the `local-as` is prepended to outgoing updates
+to the peer; the router's real ASN is omitted. The `replace-as` modifier
+requires `no-prepend` and cannot be used on its own.
```
+```{note}
+This command applies only to eBGP peers.
+```
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> nexthop-self
+Example:
-This command forces the BGP speaker to report itself as the
-next hop for an advertised route it advertised to a neighbor.
+```none
+set protocols bgp neighbor 192.0.2.2 local-as 64600 no-prepend replace-as
```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> passive
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> remove-private-as
+**Configure the local BGP speaker to only accept inbound TCP connections
+from the specified peer and never initiate an outbound connection.**
+```
-This command removes the private ASN of routes that are advertised
-to the configured peer. It removes only private ASNs on routes
-advertised to EBGP peers.
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 passive
+```
-If the AS-Path for the route has only private ASNs, the private
-ASNs are removed.
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> password \<text\>
-If the AS-Path for the route has a private ASN between public
-ASNs, it is assumed that this is a design choice, and the
-private ASN is not removed.
+**Configure a TCP MD5 authentication password for the session with the
+specified peer.**
+
+Both sides of the session must be configured with the same password for
+the connection to be established.
```
+Example:
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> soft-reconfiguration inbound
+```none
+set protocols bgp neighbor 192.0.2.2 password mysharedsecret
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> ttl-security hops \<1-254\>
+
+**Enable the {abbr}`GTSM (Generalized TTL Security Mechanism)` on the
+session with the specified peer, as defined in
+[RFC 5082](https://datatracker.ietf.org/doc/html/rfc5082).**
-Changes in BGP policies require the BGP session to be cleared. Clearing has a
-large negative impact on network operations. Soft reconfiguration enables you
-to generate inbound updates from a neighbor, change and activate BGP policies
-without clearing the BGP session.
+When enabled, outbound BGP packets are sent with TTL 255, and inbound
+packets are accepted only from peers within the configured number of
+hops.
+```
+
+```{note}
+This command is mutually exclusive with `ebgp-multihop`.
+```
-This command specifies that route updates received from this neighbor will be
-stored unmodified, regardless of the inbound policy. When inbound soft
-reconfiguration is enabled, the stored updates are processed by the new
-policy configuration to create new inbound updates.
+Example:
-:::{note}
-Storage of route updates uses memory. If you enable soft
-reconfiguration inbound for multiple neighbors, the amount of memory used
-can become significant.
-:::
+```none
+set protocols bgp neighbor 192.0.2.2 ttl-security hops 1
```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> bfd [profile \<name\>]
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> weight \<number\>
+**Enable {abbr}`BFD (Bidirectional Forwarding Detection)` on the session
+with the specified peer.**
+
+When BFD declares the path to the peer down, the BGP session is reset
+immediately rather than waiting for the BGP hold timer to expire.
+Optionally, a BFD profile (configured under `set protocols bfd profile`)
+can be applied to control detection timers and other parameters. Without
+a profile, the default BFD parameters apply.
+```
-This command specifies a default weight value for the neighbor’s
-routes. The number range is 1 to 65535.
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 bfd profile FAST-LINK
```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> bfd check-control-plane-failure
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> advertisement-interval \<seconds\>
+**Configure BGP to set and inspect the BFD C-bit (Control Plane
+Independent bit) for the session with the specified peer. This option is
+intended for use with BGP Graceful Restart.**
-This command specifies the minimum route advertisement interval for
-the peer. The interval value is 0 to 600 seconds, with the default
-advertisement interval being 0.
+The local router sets the C-bit on outgoing BFD packets and checks it on
+incoming packets to distinguish between BFD failures caused by
+control plane disruptions and those caused by data plane failures.
+
+Consequently, a BFD-down event caused by a control plane restart on the
+peer does not tear down the BGP session if the peer is still forwarding
+traffic.
+
+Without this option, every BFD-down event resets the BGP session.
+```
+
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 bfd check-control-plane-failure
```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> bfd strict
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> disable-connected-check
+**Require BFD to be up before the BGP session with the specified peer
+reaches the Established state (strict-mode BFD).**
-This command allows peerings between directly connected eBGP peers
-using loopback addresses without adjusting the default TTL of 1.
+Without strict mode, BGP establishes the session independently, and BFD
+only monitors it once both are up. With strict mode, BGP delays session
+establishment until BFD declares the path to the peer up. This prevents
+the BGP session from being established over a path that BFD will
+subsequently report as down.
```
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 bfd strict
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> bfd strict hold-time \<1-4294967295\>
+
+**Configure how long, in seconds, BGP waits before tearing down the
+session after BFD reports the path down.**
+
+This timer applies only when the BGP hold-time is `0`. Otherwise, a
+BFD-down event causes immediate BGP session teardown.
+```
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> disable-send-community \<extended|standard\>
+Example:
-This command specifies that the community attribute should not be sent
-in route updates to a peer. By default community attribute is sent.
+```none
+set protocols bgp neighbor 192.0.2.2 bfd strict hold-time 30
```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> enforce-first-as
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> ebgp-multihop \<number\>
+**Require that the first ASN in the AS_PATH of every UPDATE received
+from the specified eBGP peer matches that peer's ASN.**
-This command allows sessions to be established with eBGP neighbors
-when they are multiple hops away. When the neighbor is not directly
-connected and this knob is not enabled, the session will not establish.
-The number of hops range is 1 to 255. This command is mutually
-exclusive with {cfgcmd}`ttl-security hops`.
+If the first ASN does not match, the UPDATE is rejected.
```
+Example:
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> local-as \<asn\> [no-prepend] [replace-as]
+```none
+set protocols bgp neighbor 192.0.2.2 enforce-first-as
+```
-Specify an alternate AS for this BGP process when interacting with
-the specified peer or peer group. With no modifiers, the specified
-local-as is prepended to the received AS_PATH when receiving routing
-updates from the peer, and prepended to the outgoing AS_PATH (after
-the process local AS) when transmitting local routes to the peer.
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> path-attribute discard \<1-255\>
-If the {cfgcmd}`no-prepend` attribute is specified, then the supplied
-local-as is not prepended to the received AS_PATH.
+**Drop the specified BGP path attribute from incoming UPDATE messages
+received from this peer.**
-If the {cfgcmd}`replace-as` attribute is specified, then only the supplied
-local-as is prepended to the AS_PATH when transmitting local-route
-updates to this peer.
+The UPDATE is then processed without that attribute. The number
+`<1-255>` is the path attribute type code per the IANA BGP Path
+Attributes registry.
-:::{note}
-This command is only allowed for eBGP peers.
-:::
+Multiple attributes can be discarded by issuing the command repeatedly
+with different numbers.
```
+```{note}
+The following attributes cannot be discarded: 1 (ORIGIN), 2 (AS_PATH),
+3 (NEXT_HOP), 4 (MED), 8 (COMMUNITIES), 14 (MP_REACH_NLRI),
+15 (MP_UNREACH_NLRI), and 16 (EXTENDED_COMMUNITIES).
+```
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> passive
+Example:
-Configures the BGP speaker so that it only accepts inbound connections
-from, but does not initiate outbound connections to the peer or peer group.
+```none
+set protocols bgp neighbor 192.0.2.2 path-attribute discard 128
```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> path-attribute treat-as-withdraw \<1-255\>
+
+**Treat any incoming UPDATE that contains the specified BGP path
+attribute as a withdrawal of the routes it carries.**
+
+Use this to recover gracefully when a peer advertises malformed or
+unexpected attributes that would otherwise tear down the session.
+```
+
+```{note}
+The following attributes cannot be specified: 1 (ORIGIN), 2 (AS_PATH),
+3 (NEXT_HOP), 4 (MED), 8 (COMMUNITIES), 14 (MP_REACH_NLRI),
+15 (MP_UNREACH_NLRI), and 16 (EXTENDED_COMMUNITIES).
+```
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> password \<text\>
+Example:
-This command specifies a MD5 password to be used with the tcp socket that
-is being used to connect to the remote peer.
+```none
+set protocols bgp neighbor 192.0.2.2 path-attribute treat-as-withdraw 32
```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> maximum-prefix-out \<1-4294967295\>
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> ttl-security hops \<number\>
+**Configure the maximum number of prefixes the local BGP speaker will
+advertise to the specified peer.**
+
+Unlike `maximum-prefix`, which limits inbound prefixes and tears down
+the session when the limit is exceeded, `maximum-prefix-out` simply
+stops sending additional prefixes outbound once the limit is reached.
+The session remains up.
+```
-This command enforces Generalized TTL Security Mechanism (GTSM),
-as specified in {rfc}`5082`. With this command, only neighbors
-that are specified number of hops away will be allowed to
-become neighbors. The number of hops range is 1 to 254. This
-command is mutually exclusive with {cfgcmd}`ebgp-multihop`.
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast maximum-prefix-out 5000
```
-##### Peer Groups
+#### Peer groups
-Peer groups are used to help improve scaling by generating the same update
-information to all members of a peer group. Note that this means that the
-routes generated by a member of a peer group will be sent back to that
-originating peer with the originator identifier attribute set to indicated
-the originating peer. All peers not associated with a specific peer group
-are treated as belonging to a default peer group, and will share updates.
+Peer groups serve two purposes. First, they simplify configuration:
+parameters applied to a group are inherited by all its members, so
+common settings have to be configured only once and in one place.
+Second, they improve scalability by computing outgoing update
+information once per group rather than for each group member.
+
+As a side effect, a route advertised by one group member is
+re-advertised to all group members, including the sender itself. The
+originator identifier attribute is included in such updates so that the
+originating peer can recognize its own routes and ignore them.
+
+Peers not explicitly assigned to any peer group are treated as members
+of the default peer group and share updates with that group.
```{cfgcmd} set protocols bgp peer-group \<name\>
- This command defines a new peer group. You can specify to the group the same
- parameters that you can specify for specific neighbors.
+**Configure a BGP peer group.**
- :::{note}
- If you apply a parameter to an individual neighbor IP address, you
- override the action defined for a peer group that includes that IP
- address.
- :::
+A peer group accepts the same parameters that can be applied to
+individual neighbors.
```
+```{note}
+A parameter applied directly to an individual neighbor IP address
+overrides the same parameter applied to a peer group that includes that
+neighbor.
+```
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> peer-group \<name\>
+Example:
-This command bind specific peer to peer group with a given name.
+```none
+set protocols bgp peer-group UPSTREAM
```
-#### Network Advertisement Configuration
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> peer-group \<name\>
-```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> network \<prefix\>
+**Assign the specified neighbor to a peer group.**
-This command is used for advertising IPv4 or IPv6 networks.
+The neighbor inherits all parameters configured on the peer group.
+```
- :::{note}
- By default, the BGP prefix is advertised even if it's not present
- in the routing table. This behaviour differs from the implementation of
- some vendors.
- :::
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 peer-group UPSTREAM
```
+### Network advertisement configuration
+
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast | ipv6-unicast\> network \<prefix\>
+
+**Configure BGP to originate and advertise the specified IPv4 or IPv6
+prefix.**
+```
+
+```{note}
+By default, BGP advertises a prefix configured via the `network` statement
+even if the prefix is not present in the routing table. To make BGP verify
+that the prefix exists in the RIB before advertising it (the behavior of
+some other vendors' routers), enable the `network-import-check` option.
+```
+
+Example:
+
+```none
+set protocols bgp address-family ipv4-unicast network 198.51.100.0/24
+```
+
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast | ipv6-unicast\> network \<prefix\> route-map \<name\>
+
+**Apply a route-map to set attributes on, or suppress, the locally
+originated network route.**
+
+The `route-map` is evaluated when BGP originates the route and can set
+communities, MED, LOCAL_PREF, or other path attributes on the originated
+route. If the `route-map` denies the prefix, BGP does not originate the
+route.
+```
+
+Example:
+
+```none
+set protocols bgp address-family ipv4-unicast network 198.51.100.0/24 route-map SET-COMMUNITY
+```
+
+```{cfgcmd} set protocols bgp address-family ipv6-unicast network \<prefix\> path-limit \<0-255\>
+
+**Configure the AS_PATHLIMIT attribute on the originated IPv6 route.**
+
+The AS_PATHLIMIT attribute sets an upper bound on the number of ASes the
+route may traverse before being dropped. A value of `0` disables the
+limit.
+```
+
+Example:
+
+```none
+set protocols bgp address-family ipv6-unicast network 2001:db8::/48 path-limit 8
+```
```{cfgcmd} set protocols bgp parameters network-import-check
-This configuration modifies the behavior of the network statement. If you
-have this configured the underlying network must exist in the routing table.
+**Configure BGP to verify that a prefix defined by the `network` command
+exists in the routing table (RIB) before it is advertised to BGP peers.**
+```
+
+Example:
+
+```none
+set protocols bgp parameters network-import-check
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> default-originate [route-map \<name\>]
+
+**Configure BGP to advertise a default route (`0.0.0.0/0` or `::/0`) to
+the specified peer.**
+
+By default, VyOS does not advertise a default route even if one is
+present in the routing table.
+
+When a `route-map` is used, the default route is only advertised if the
+conditions specified in the `route-map` are met.
+```
+
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast default-originate
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> addpath-tx-all
+
+**Configure BGP to use ADD-PATH to advertise every known path for each
+prefix to the specified peer, not only the best path.**
+```
+
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast addpath-tx-all
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> addpath-tx-per-as
+
+**Configure BGP to use ADD-PATH to advertise the best path per
+neighboring AS to the specified peer.**
+```
+
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast addpath-tx-per-as
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> conditionally-advertise advertise-map \<name\>
+
+**Configure BGP to advertise the prefixes allowed by the specified
+`route-map` only when the `exist-map` or `non-exist-map` condition is
+met.**
+```
+
+```{note}
+This option must be used together with either
+`conditionally-advertise exist-map` or
+`conditionally-advertise non-exist-map`, as `advertise-map` alone does
+not enable conditional advertisement.
+```
+
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast conditionally-advertise advertise-map BACKUP-ROUTES
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> conditionally-advertise exist-map \<name\>
+
+**Specify the route-map that defines the trigger condition for
+`advertise-map`.**
+
+The condition is met when at least one prefix allowed by the specified
+`route-map` is present in the BGP RIB.
+```
+
+```{note}
+`exist-map` and `non-exist-map` are mutually exclusive.
+```
+
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast conditionally-advertise exist-map AGGREGATE-PRESENT
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> conditionally-advertise non-exist-map \<name\>
+
+**Specify the route-map that defines the trigger condition for
+`advertise-map`.**
+
+The condition is met when no prefix allowed by the specified `route-map`
+is present in the BGP RIB.
+```
+
+```{note}
+`exist-map` and `non-exist-map` are mutually exclusive.
+```
+
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast conditionally-advertise non-exist-map PRIMARY-UP
+```
+
+### Route aggregation configuration
+
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast | ipv6-unicast\> aggregate-address \<prefix\>
+
+**Configure BGP to advertise an aggregate route for the specified IPv4
+or IPv6 prefix.**
+
+By default, BGP also advertises more-specific routes that fall within
+the aggregate.
+```
+
+Example:
+
+```none
+set protocols bgp address-family ipv4-unicast aggregate-address 198.51.100.0/22
+```
+
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast | ipv6-unicast\> aggregate-address \<prefix\> as-set
+
+**Configure BGP to advertise an aggregate route with an AS_SET segment
+in its AS_PATH for the specified IPv4 or IPv6 prefix.**
+
+The AS_SET contains the AS numbers from the AS_PATHs of all contributing
+more specific routes.
+```
+
+Example:
+
+```none
+set protocols bgp address-family ipv4-unicast aggregate-address 198.51.100.0/22 as-set
+```
+
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast | ipv6-unicast\> aggregate-address \<prefix\> summary-only
+
+**Configure BGP to advertise only the aggregate route and suppress
+advertisement of more-specific contributing routes.**
+```
+
+Example:
+
+```none
+set protocols bgp address-family ipv4-unicast aggregate-address 198.51.100.0/22 summary-only
+```
+
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast | ipv6-unicast\> aggregate-address \<prefix\> route-map \<name\>
+
+**Apply a `route-map` to set or modify BGP path attributes on the aggregate
+route before it is advertised.**
+
+Attribute changes apply only to the aggregate route and do not affect more
+specific contributing routes. Use the `route-map` to set communities, MED,
+LOCAL_PREF, or other attributes carried by the summary advertisement.
+```
+
+Example:
+
+```none
+set protocols bgp address-family ipv4-unicast aggregate-address 198.51.100.0/22 route-map AGGREGATE-ATTRS
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> unsuppress-map \<name\>
+
+**Apply a route-map to selectively advertise to the specified peer
+more specific routes that were suppressed by the `summary-only` option.**
+```
+
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast unsuppress-map UNSUPPRESS-MORE-SPECIFIC
+```
+
+### Redistribution configuration
+
+```{cfgcmd} set protocols bgp address-family ipv4-unicast redistribute \<babel | connected | isis | kernel | nhrp | ospf | rip | static\>
+
+**Redistribute IPv4 unicast routes from the specified source into BGP.**
```
+Example:
+
+```none
+set protocols bgp address-family ipv4-unicast redistribute connected
+```
+
+```{cfgcmd} set protocols bgp address-family ipv4-unicast redistribute table \<id\>
+
+**Redistribute IPv4 routes from the specified non-main kernel routing
+table (identified by `<id>`, configured under
+`set protocols static table`) into the BGP IPv4 unicast address family.**
+```
+
+Example:
+
+```none
+set protocols bgp address-family ipv4-unicast redistribute table 100
+```
+
+```{cfgcmd} set protocols bgp address-family ipv6-unicast redistribute \<babel | connected | isis | kernel | nhrp | ospfv3 | ripng | static\>
+
+**Redistribute IPv6 unicast routes from the specified source into BGP.**
+```
+
+Example:
+
+```none
+set protocols bgp address-family ipv6-unicast redistribute connected
+```
+
+```{cfgcmd} set protocols bgp address-family ipv6-unicast redistribute table \<id\>
+
+**Redistribute IPv6 routes from the specified non-main kernel routing
+table (identified by `<id>`, configured under
+`set protocols static table`) into the BGP IPv6 unicast address family.**
+```
+
+Example:
+
+```none
+set protocols bgp address-family ipv6-unicast redistribute table 100
+```
+
+```{cfgcmd} set protocols bgp address-family ipv4-unicast redistribute \<babel | connected | isis | kernel | nhrp | ospf | rip | static\> metric \<1-4294967295\>
+
+**Redistribute IPv4 unicast routes from the specified source into BGP,
+setting the MED attribute on the redistributed routes to the specified
+value.**
+```
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> default-originate [route-map \<name\>]
+Example:
-By default, VyOS does not advertise a default route (0.0.0.0/0) even if it is
-in routing table. When you want to announce default routes to the peer, use
-this command. Using optional argument {cfgcmd}`route-map` you can inject the
-default route to given neighbor only if the conditions in the route map are
-met.
+```none
+set protocols bgp address-family ipv4-unicast redistribute static metric 100
```
-#### Route Aggregation Configuration
+```{cfgcmd} set protocols bgp address-family ipv4-unicast redistribute table \<id\> metric \<1-4294967295\>
-```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> aggregate-address \<prefix\>
+**Redistribute IPv4 routes from the specified non-main kernel routing
+table into the BGP IPv4 unicast address family, setting the MED attribute
+on the redistributed routes to the specified value.**
+```
-This command specifies an aggregate address. The router will also
-announce longer-prefixes inside of the aggregate address.
+Example:
+
+```none
+set protocols bgp address-family ipv4-unicast redistribute table 100 metric 100
```
+```{cfgcmd} set protocols bgp address-family ipv6-unicast redistribute \<babel | connected | isis | kernel | nhrp | ospfv3 | ripng | static\> metric \<1-4294967295\>
-```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> aggregate-address \<prefix\> as-set
+**Redistribute IPv6 unicast routes from the specified source into BGP,
+setting the MED attribute on the redistributed routes to the specified
+value.**
+```
+
+Example:
-This command specifies an aggregate address with a mathematical set of
-autonomous systems. This command summarizes the AS_PATH attributes of
-all the individual routes.
+```none
+set protocols bgp address-family ipv6-unicast redistribute static metric 100
```
+```{cfgcmd} set protocols bgp address-family ipv6-unicast redistribute table \<id\> metric \<1-4294967295\>
-```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> aggregate-address \<prefix\> summary-only
+**Redistribute IPv6 routes from the specified non-main kernel routing
+table into the BGP IPv6 unicast address family, setting the MED attribute
+on the redistributed routes to the specified value.**
+```
+
+Example:
-This command specifies an aggregate address and provides that
-longer-prefixes inside of the aggregate address are suppressed
-before sending BGP updates out to peers.
+```none
+set protocols bgp address-family ipv6-unicast redistribute table 100 metric 100
```
+```{cfgcmd} set protocols bgp address-family ipv4-unicast redistribute \<babel | connected | isis | kernel | nhrp | ospf | rip | static\> route-map \<name\>
+
+**Apply a route-map to filter and modify IPv4 unicast routes
+redistributed from the specified source.**
+```
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> unsuppress-map \<name\>
+Example:
-This command applies route-map to selectively unsuppress prefixes
-suppressed by summarisation.
+```none
+set protocols bgp address-family ipv4-unicast redistribute static route-map FILTER-STATIC
```
-#### Redistribution Configuration
+```{cfgcmd} set protocols bgp address-family ipv4-unicast redistribute table \<id\> route-map \<name\>
+
+**Apply a `route-map` to filter and modify IPv4 routes redistributed from
+the specified non-main kernel routing table into the BGP IPv4 unicast
+address family.**
+```
-```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> redistribute <route source>
+Example:
-This command redistributes routing information from the given route source
-to the BGP process. There are six modes available for route source:
-connected, kernel, ospf, rip, static, table.
+```none
+set protocols bgp address-family ipv4-unicast redistribute table 100 route-map FILTER-STATIC
```
+```{cfgcmd} set protocols bgp address-family ipv6-unicast redistribute \<babel | connected | isis | kernel | nhrp | ospfv3 | ripng | static\> route-map \<name\>
-```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> redistribute <route source> metric \<number\>
+**Apply a `route-map` to filter and modify IPv6 unicast routes
+redistributed from the specified source.**
+```
-This command specifies metric (MED) for redistributed routes. The
-metric range is 0 to 4294967295. There are six modes available for
-route source: connected, kernel, ospf, rip, static, table.
+Example:
+
+```none
+set protocols bgp address-family ipv6-unicast redistribute static route-map FILTER-STATIC
```
+```{cfgcmd} set protocols bgp address-family ipv6-unicast redistribute table \<id\> route-map \<name\>
-```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> redistribute <route source> route-map \<name\>
+**Apply a `route-map` to filter and modify IPv6 routes redistributed from
+the specified non-main kernel routing table into the BGP IPv6 unicast
+address family.**
+```
-This command allows to use route map to filter redistributed routes.
-There are six modes available for route source: connected, kernel,
-ospf, rip, static, table.
+Example:
+
+```none
+set protocols bgp address-family ipv6-unicast redistribute table 100 route-map FILTER-STATIC
```
-#### General Configuration
-##### Common parameters
+### General configuration
+
+#### Common parameters
```{cfgcmd} set protocols bgp parameters allow-martian-nexthop
- When a peer receives a martian nexthop as part of the NLRI for a route
- permit the nexthop to be used as such, instead of rejecting and resetting
- the connection.
+**Configure BGP to accept UPDATE messages whose NEXT_HOP attribute is
+a Martian address.**
+
+A Martian address is one that cannot legitimately appear as a BGP
+next hop, such as an all-zero or unspecified address (e.g., `0.0.0.0/8`
+or `::`), a loopback address (e.g., `127.0.0.0/8` or `::1`), a
+multicast address, or an address of the local router itself.
+
+By default, BGP rejects such routes.
```
+Example:
+
+```none
+set protocols bgp parameters allow-martian-nexthop
+```
```{cfgcmd} set protocols bgp parameters router-id \<id\>
-This command specifies the router-ID. If router ID is not specified it will
-use the highest interface IP address.
+**Configure the BGP router-ID as a 32-bit identifier in IPv4 address
+notation.**
+
+If no router ID is configured, VyOS uses the highest IPv4 address on the
+loopback interface. If no loopback address is configured, VyOS uses the
+highest IPv4 address on any other interface.
```
+Example:
-```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> maximum-paths \<ebgp|ibgp\> \<number\>
+```none
+set protocols bgp parameters router-id 192.0.2.1
+```
-This command defines the maximum number of parallel routes that
-the BGP can support. In order for BGP to use the second path, the
-following attributes have to match: Weight, Local Preference, AS
-Path (both AS number and AS path length), Origin code, MED, IGP
-metric. Also, the next hop address for each path must be different.
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast | ipv6-unicast\> maximum-paths \<ebgp | ibgp\> \<1-256\>
+
+**Configure the maximum number of parallel BGP paths that can be
+installed for the same destination
+({abbr}`ECMP (Equal-Cost Multi-Path)`).**
+
+For paths to be considered equal for multipath purposes, the following
+must match: weight, local preference, AS_PATH content and length, origin
+code, MED, and IGP metric. Each path must also have a distinct next hop
+IP address.
```
+Example:
+
+```none
+set protocols bgp address-family ipv4-unicast maximum-paths ebgp 4
+```
```{cfgcmd} set protocols bgp parameters no-hard-administrative-reset
-Do not send Hard Reset CEASE Notification for "Administrative Reset"
-events. When set and Graceful Restart Notification capability is exchanged
-between the peers, Graceful Restart procedures apply, and routes will be retained.
+**Suppress sending a Hard Reset CEASE notification for Administrative
+Reset events.**
+
+When this option is enabled, routes are retained across an administrative
+reset, provided the Graceful Restart Notification capability has been
+negotiated between the peers.
```
+Example:
+
+```none
+set protocols bgp parameters no-hard-administrative-reset
+```
```{cfgcmd} set protocols bgp parameters log-neighbor-changes
-This command enable logging neighbor up/down changes and reset reason.
+**Configure BGP to log neighbor up/down state changes and reset reasons
+to syslog.**
```
+Example:
+
+```none
+set protocols bgp parameters log-neighbor-changes
+```
```{cfgcmd} set protocols bgp parameters no-client-to-client-reflection
-This command disables route reflection between route reflector clients.
-By default, the clients of a route reflector are not required to be
-fully meshed and the routes from a client are reflected to other clients.
-However, if the clients are fully meshed, route reflection is not required.
-In this case, use the {cfgcmd}`no-client-to-client-reflection` command
-to disable client-to-client reflection.
+**Disable route reflection between route-reflector clients on this
+router.**
+
+By default, a route reflector reflects routes received from one client
+to all other clients. If the clients are fully meshed with iBGP, this
+reflection is unnecessary and can be disabled with this option.
```
+Example:
+
+```none
+set protocols bgp parameters no-client-to-client-reflection
+```
```{cfgcmd} set protocols bgp parameters no-fast-external-failover
-Disable immediate session reset if peer's connected link goes down.
+**Disable immediate session reset when the connected link to an eBGP
+peer goes down.**
+
+By default, BGP resets the session immediately on link-down events. With
+this option set, the session is held until the hold timer expires.
```
+Example:
+
+```none
+set protocols bgp parameters no-fast-external-failover
+```
```{cfgcmd} set protocols bgp parameters no-ipv6-auto-ra
-By default, FRR sends router advertisement packets when Extended Next Hop is
-on or when a connection is established directly using the device name (Unnumbered BGP).
-Setting this option prevents FRR from sending router advertisement packets, but could break Unnumbered BGP.
+**Suppress automatic IPv6 Router Advertisement (RA) on interfaces used
+for BGP.**
+
+By default, FRR sends RAs on an interface when its BGP session has
+negotiated the Extended Next Hop capability, or when a BGP neighbor is
+configured by interface name (Unnumbered BGP).
+```
+
+```{note}
+Setting this option may prevent Unnumbered BGP sessions from
+establishing.
```
+Example:
+
+```none
+set protocols bgp parameters no-ipv6-auto-ra
+```
```{cfgcmd} set protocols bgp listen range \<prefix\> peer-group \<name\>
-This command is useful if one desires to loosen the requirement for BGP
-to have strictly defined neighbors. Specifically what is allowed is for
-the local router to listen to a range of IPv4 or IPv6 addresses defined
-by a prefix and to accept BGP open messages. When a TCP connection
-(and subsequently a BGP open message) from within this range tries to
-connect the local router then the local router will respond and connect
-with the parameters that are defined within the peer group. One must define
-a peer-group for each range that is listed. If no peer-group is defined
-then an error will keep you from committing the configuration.
+**Configure BGP to accept inbound connections from any source IP address
+within the specified prefix and associate them with the specified peer
+group.**
+
+This removes the need to statically define each BGP neighbor. When a TCP
+connection and OPEN message arrive from a source IP address within the
+specified prefix, the local router accepts the session using the peer
+group's parameters.
+```
+
+```{note}
+For each listen range, the referenced peer group must exist before the
+configuration is committed.
```
+Example:
-```{cfgcmd} set protocols bgp listen limit \<number\>
+```none
+set protocols bgp listen range 192.0.2.0/24 peer-group UPSTREAM
+```
-This command goes hand in hand with the listen range command to limit the
-amount of BGP neighbors that are allowed to connect to the local router.
-The limit range is 1 to 5000.
+```{cfgcmd} set protocols bgp listen limit \<1-5000\>
+
+**Configure the maximum number of dynamic BGP neighbors the local router
+will accept via configured listen ranges.**
```
+Example:
+
+```none
+set protocols bgp listen limit 100
+```
```{cfgcmd} set protocols bgp parameters ebgp-requires-policy
-This command changes the eBGP behavior of FRR. By default FRR enables
-{rfc}`8212` functionality which affects how eBGP routes are advertised,
-namely no routes are advertised across eBGP sessions without some
-sort of egress route-map/policy in place. In VyOS however we have this
-RFC functionality disabled by default so that we can preserve backwards
-compatibility with older versions of VyOS. With this option one can
-enable {rfc}`8212` functionality to operate.
+**Require an explicit policy in each direction on eBGP sessions before
+exchanging routes
+([RFC 8212](https://datatracker.ietf.org/doc/html/rfc8212)).**
+
+By default, VyOS disables this RFC 8212 behavior for backward
+compatibility with older VyOS versions. Enabling it brings VyOS into
+compliance with the default route propagation behavior expected by
+RFC 8212.
```
+Example:
+
+```none
+set protocols bgp parameters ebgp-requires-policy
+```
```{cfgcmd} set protocols bgp parameters labeled-unicast \<explicit-null | ipv4-explicit-null | ipv6-explicit-null\>
-By default, locally advertised prefixes use the implicit-null label to
-encode in the outgoing NLRI.
+**Configure {abbr}`BGP-LU (BGP Labeled Unicast)` to advertise locally
+originated prefixes with an explicit-null label instead of the default
+implicit-null label, preserving the MPLS label at the egress.**
+```
+
+Example:
+
+```none
+set protocols bgp parameters labeled-unicast explicit-null
+```
+<!-- CLI path not accepted on live VyOS
+```{cfgcmd} set protocols bgp parameters as-notation \<asdot | asdot+ | asplain\>
+
+- `asplain`: Print every ASN in plain decimal. This is the default.
+- `asdot`: Print ASNs greater than 65535 in dotted notation (e.g.,
+ `65540` becomes `1.4`). ASNs at or below 65535 are printed in plain
+ decimal.
+- `asdot+`: Print every ASN in dotted notation.
+```
+
+Example:
+
+```none
+set protocols bgp parameters as-notation asdot
+```
+-->
+
+```{cfgcmd} set protocols bgp parameters disable-ebgp-connected-route-check
+
+**Allow eBGP-learned routes whose NEXT_HOP is not directly connected to
+be installed in the RIB.**
+
+By default, BGP requires the next hop of an eBGP-learned route to be
+reachable through a directly connected route. This option removes
+that restriction.
+```
+
+Example:
+
+```none
+set protocols bgp parameters disable-ebgp-connected-route-check
+```
+
+```{cfgcmd} set protocols bgp parameters fast-convergence
+
+**Configure BGP to tear down its sessions immediately whenever the
+local router detects that a peer has become unreachable.**
+
+This triggers on both direct link-down events and NEXT_HOP reachability
+changes signaled by the IGP.
+```
+
+Example:
+
+```none
+set protocols bgp parameters fast-convergence
+```
+
+```{cfgcmd} set protocols bgp parameters no-suppress-duplicates
+
+**Disable suppression of duplicate UPDATE messages for routes whose
+attributes have not changed.**
+
+By default, BGP suppresses repeated advertisements of the same route
+with unchanged attributes. Setting this option disables that
+suppression.
+```
+
+Example:
-The following command uses the explicit-null label value for all the
-BGP instances.
+```none
+set protocols bgp parameters no-suppress-duplicates
```
-##### Administrative Distance
+```{cfgcmd} set protocols bgp parameters reject-as-sets
+
+**Configure BGP to reject incoming UPDATE messages whose AS_PATH
+contains an AS_SET or AS_CONFED_SET segment.**
+
+AS_SET segments are deprecated for most modern deployments.
+```
-```{cfgcmd} set protocols bgp parameters distance global \<external|internal|local\> \<distance\>
+Example:
-This command change distance value of BGP. The arguments are the distance
-values for external routes, internal routes and local routes respectively.
-The distance range is 1 to 255.
+```none
+set protocols bgp parameters reject-as-sets
```
+```{cfgcmd} set protocols bgp parameters suppress-fib-pending
-```{cfgcmd} set protocols bgp parameters distance prefix \<subnet\> distance \<distance\>
+**Configure BGP not to advertise a route to peers until the route is
+installed in the kernel forwarding table (FIB).**
-This command sets the administrative distance for a particular route. The
-distance range is 1 to 255.
+This prevents the local router from advertising a route it cannot yet
+forward.
+```
-:::{note}
-Routes with a distance of 255 are effectively disabled and not
-installed into the kernel.
-:::
+Example:
+
+```none
+set protocols bgp parameters suppress-fib-pending
```
-##### BGP message queue limits
+```{cfgcmd} set protocols bgp parameters shutdown
+
+**Administratively shut down the entire BGP instance on this router.**
+
+This terminates all BGP sessions belonging to this instance.
+```
+
+Example:
+
+```none
+set protocols bgp parameters shutdown
+```
```{cfgcmd} set protocols bgp parameters input-queue-limit \<messages\>
- Set the BGP Input Queue limit for all peers during message parsing.
- Increase this only if you have the memory to handle large queues of
- messages at once.
+**Set the BGP input queue limit for all peers during message parsing.**
- The default is 10000.
+Increase this only if you have the memory to handle large queues of
+messages at once. The default is 10000.
+```
+
+Example:
+
+```none
+set protocols bgp parameters input-queue-limit 10000
```
```{cfgcmd} set protocols bgp parameters output-queue-limit \<messages\>
- Set the BGP Output Queue limit for all peers during message parsing.
- Increase this only if you have the memory to handle large queues of
- messages at once.
+**Set the BGP output queue limit for all peers during message parsing.**
+
+Increase this only if you have the memory to handle large queues of
+messages at once. The default is 10000.
+```
+
+Example:
+
+```none
+set protocols bgp parameters output-queue-limit 10000
+```
+
+#### Graceful restart and shutdown
+
+```{cfgcmd} set protocols bgp parameters graceful-restart stalepath-time \<1-3600\>
+
+**Configure the maximum time, in seconds, that the local router retains
+stale routes from a restarting peer.**
+
+When a BGP peer signals Graceful Restart, the local router marks the
+peer's routes as stale and continues forwarding traffic on them while
+the session is down. If the peer does not complete the Graceful Restart
+(re-establish the session and send the End-of-RIB marker) within
+`stalepath-time`, the stale routes are removed.
+```
+
+Example:
+
+```none
+set protocols bgp parameters graceful-restart stalepath-time 360
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> graceful-restart \<enable | disable | restart-helper\>
+
+**Configure the Graceful Restart role for the specified peer:**
+
+- `enable`: Advertises the GR capability and allows both restart and
+ helper roles.
+- `disable`: Disables GR for this peer.
+- `restart-helper`: Advertises only the helper role. The local router
+ retains the peer's routes across a peer restart but does not advertise
+ the restart capability for itself.
+```
+
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 graceful-restart restart-helper
+```
+
+```{cfgcmd} set protocols bgp parameters graceful-shutdown
+
+**Configure BGP to tag all outbound routes with the GRACEFUL_SHUTDOWN
+community, signaling to neighbors that they should prefer alternative
+paths.**
+```
- The default is 10000.
+Example:
+
+```none
+set protocols bgp parameters graceful-shutdown
```
-##### Timers
+#### Administrative distance
+
+```{cfgcmd} set protocols bgp parameters distance global \<external | internal | local\> \<1-255\>
+
+**Configure the administrative distance assigned to BGP routes of the
+specified category.**
+
+`external` covers eBGP-learned routes, `internal` covers iBGP-learned
+routes, and `local` covers locally originated BGP routes.
+```
-```{cfgcmd} set protocols bgp timers holdtime \<seconds\>
+Example:
- This command specifies hold-time in seconds. The timer range is
- 4 to 65535. The default value is 180 second. If you set value to 0
- VyOS will not hold routes.
+```none
+set protocols bgp parameters distance global external 20
```
+```{cfgcmd} set protocols bgp parameters distance prefix \<subnet\> distance \<1-255\>
-```{cfgcmd} set protocols bgp timers keepalive \<seconds\>
+**Override the BGP administrative distance for routes matching the
+specified prefix.**
+```
-This command specifies keep-alive time in seconds. The timer
-can range from 4 to 65535. The default value is 60 second.
+```{note}
+A distance value of 255 effectively disables the route. It is not
+installed in the kernel forwarding table.
```
+Example:
-##### BGP read-only mode
+```none
+set protocols bgp parameters distance prefix 198.51.100.0/24 distance 200
+```
-```{eval-rst}
-.. cfgcmd:: set protocols bgp parameters update-delay max-delay <seconds>
+The commands above set process-wide BGP distances under `parameters
+distance`. Per-address-family distances can also be configured under each
+`address-family` node and override the process-wide values for routes in
+that address family.
-**Enable BGP read-only mode after a BGP process restart or clearing all BGP sessions, and configure the mode’s maximum delay.**
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast | ipv6-unicast\> distance \<external | internal | local\> \<1-255\>
-In read-only mode, BGP suspends best-path selection and does not send routing
-updates to peers. The mode ends when the router receives all expected
-End-of-RIB (EOR) messages from BGP peers or when the maximum delay is
-reached, whichever occurs first.
+**Configure the administrative distance assigned to BGP routes of the
+specified category within the selected address family.**
-The router expects EOR messages from all configured BGP peers except those
-that are administratively shut down. If the ``establish-wait`` parameter is
-configured, the router waits for EOR messages only from BGP peers that reach
-the Established state within the ``establish-wait`` window.
+`external` covers eBGP-learned routes, `internal` covers iBGP-learned
+routes, and `local` covers locally originated BGP routes.
-The allowed range is 0 to 3600 seconds. By default, this feature is disabled.
+Per-address-family values configured here override the corresponding
+values set by `set protocols bgp parameters distance global` for that
+address family.
+```
Example:
-.. code-block:: none
+```none
+set protocols bgp address-family ipv4-unicast distance external 20
+```
+
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast | ipv6-unicast\> distance prefix \<subnet\> distance \<1-255\>
+
+**Override the BGP administrative distance for routes matching the
+specified prefix within the selected address family.**
- set protocols bgp parameters update-delay max-delay 120
+Per-address-family values configured here override the corresponding
+values set by `set protocols bgp parameters distance prefix` for that
+address family.
```
-```{eval-rst}
-.. cfgcmd:: set protocols bgp parameters update-delay establish-wait <seconds>
+```{note}
+A distance value of 255 effectively disables the route. It is not
+installed in the kernel forwarding table.
+```
-**Configure how long the router waits for BGP peers to reach the Established state after read-only mode begins.**
+Example:
-The router waits for EOR messages only from BGP peers that reach the
-Established state within the ``establish-wait`` window. The ``establish-wait``
-value must not exceed the ``max-delay`` value.
+```none
+set protocols bgp address-family ipv4-unicast distance prefix 198.51.100.0/24 distance 200
+```
+
+#### Timers
+
+```{cfgcmd} set protocols bgp timers holdtime \<0-65535\>
+
+**Configure the BGP hold time, in seconds.**
+
+The default is 180 seconds. Setting the value to 0 disables the hold
+timer and keepalive exchange entirely.
+[RFC 4271](https://datatracker.ietf.org/doc/html/rfc4271) section 4.2
+requires the Hold Time to be either 0 or at least 3 seconds; the VyOS
+CLI accepts values of 1 and 2, but a session established with such a
+value will not be standards-compliant.
+```
+
+Example:
+
+```none
+set protocols bgp timers holdtime 90
+```
+
+```{cfgcmd} set protocols bgp timers keepalive \<1-65535\>
+
+**Configure the BGP keepalive interval, in seconds.**
+```
+
+Example:
+
+```none
+set protocols bgp timers keepalive 30
+```
+
+```{cfgcmd} set protocols bgp parameters minimum-holdtime \<1-65535\>
+
+**Configure BGP to reject incoming OPEN messages from peers that
+propose a hold time shorter than the specified value, in seconds.**
+```
+
+Example:
+
+```none
+set protocols bgp parameters minimum-holdtime 30
+```
+
+```{cfgcmd} set protocols bgp parameters tcp-keepalive idle \<1-65535\>
+
+**Configure the TCP keepalive idle time, in seconds, on BGP sessions.**
+
+Once no TCP packets have been exchanged in either direction on the BGP
+session for this period, the BGP process starts sending TCP keepalive
+probes.
+```
+
+```{note}
+Must be set together with `tcp-keepalive interval` and
+`tcp-keepalive probes`.
+```
+
+Example:
+
+```none
+set protocols bgp parameters tcp-keepalive idle 60
+```
+
+```{cfgcmd} set protocols bgp parameters tcp-keepalive interval \<1-65535\>
+
+**Configure the interval, in seconds, between TCP keepalive probes on
+BGP sessions.**
+
+After the BGP process begins sending TCP keepalive probes (see
+`tcp-keepalive idle`), subsequent probes are sent at this interval.
+```
+
+```{note}
+Must be set together with `tcp-keepalive idle` and
+`tcp-keepalive probes`.
+```
+
+Example:
+
+```none
+set protocols bgp parameters tcp-keepalive interval 10
+```
+
+```{cfgcmd} set protocols bgp parameters tcp-keepalive probes \<1-30\>
+
+**Configure the maximum number of unanswered TCP keepalive probes
+before the TCP connection is dropped.**
+```
+
+```{note}
+Must be set together with `tcp-keepalive idle` and
+`tcp-keepalive interval`.
+```
+
+Example:
+
+```none
+set protocols bgp parameters tcp-keepalive probes 5
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> timers holdtime \<0-65535\>
+
+**Override the BGP hold time for the specified peer, in seconds.**
+
+This option takes precedence over the process-wide `set protocols bgp
+timers holdtime`. Setting the value to `0` disables the hold timer and
+keepalive exchange for this peer.
+```
+
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 timers holdtime 30
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> timers keepalive \<1-65535\>
+
+**Override the BGP keepalive interval for the specified peer, in
+seconds.**
+
+This option takes precedence over the process-wide `set protocols bgp
+timers keepalive`.
+```
+
+Example:
-The allowed range is 1 to 3600 seconds. This parameter requires ``max-delay`` to
-be configured.
+```none
+set protocols bgp neighbor 192.0.2.2 timers keepalive 10
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> timers connect \<0-65535\>
+
+**Configure the BGP ConnectRetry timer for the specified peer, in
+seconds.**
+
+This is the interval the local BGP speaker waits between TCP connection
+attempts to a peer that is not yet in the Established state. Setting the
+value to `0` disables the ConnectRetry timer.
+```
Example:
-.. code-block:: none
+```none
+set protocols bgp neighbor 192.0.2.2 timers connect 5
+```
+
+#### BGP read-only mode
+
+```{cfgcmd} set protocols bgp parameters update-delay max-delay \<0-3600\>
+
+**Enable BGP read-only mode after a BGP process restart or after clearing
+all BGP sessions, and configure the mode's maximum delay.**
- set protocols bgp parameters update-delay establish-wait 90
+In read-only mode, BGP suspends best-path selection and does not send
+routing updates to peers. The mode ends when the router receives all
+expected {abbr}`EOR (End-of-RIB)` messages from BGP peers or when the
+maximum delay is reached, whichever occurs first.
+
+The router expects EOR messages from all configured BGP peers except
+those that are administratively shut down. If the `establish-wait`
+parameter is configured, the router waits for EOR messages only from BGP
+peers that reach the Established state within the `establish-wait`
+window.
+
+By default, BGP read-only mode is disabled.
```
-##### Route Dampening
+Example:
-When a route fails, a routing update is sent to withdraw the route from the
-network's routing tables. When the route is re-enabled, the change in
-availability is also advertised. A route that continually fails and returns
-requires a great deal of network traffic to update the network about the
-route's status.
+```none
+set protocols bgp parameters update-delay max-delay 120
+```
-Route dampening wich described in {rfc}`2439` enables you to identify routes
-that repeatedly fail and return. If route dampening is enabled, an unstable
-route accumulates penalties each time the route fails and returns. If the
-accumulated penalties exceed a threshold, the route is no longer advertised.
-This is route suppression. Routes that have been suppressed are re-entered
-into the routing table only when the amount of their penalty falls below a
-threshold.
+```{cfgcmd} set protocols bgp parameters update-delay establish-wait \<1-3600\>
-A penalty of 1000 is assessed each time the route fails. When the penalties
-reach a predefined threshold (suppress-value), the router stops advertising
-the route.
+**Configure how long the router waits for BGP peers to reach the
+Established state after read-only mode begins.**
-Once a route is assessed a penalty, the penalty is decreased by half each time
-a predefined amount of time elapses (half-life-time). When the accumulated
-penalties fall below a predefined threshold (reuse-value), the route is
-unsuppressed and added back into the BGP routing table.
+The router waits for EOR messages only from BGP peers that reach the
+Established state within the `establish-wait` window. The
+`establish-wait` value must not exceed the `max-delay` value.
+```
-No route is suppressed indefinitely. Maximum-suppress-time defines the maximum
-time a route can be suppressed before it is re-advertised.
+```{note}
+This parameter requires `max-delay` to be configured.
+```
-```{cfgcmd} set protocols bgp parameters dampening half-life \<minutes\>
+Example:
-This command defines the amount of time in minutes after
-which a penalty is reduced by half. The timer range is
-10 to 45 minutes.
+```none
+set protocols bgp parameters update-delay establish-wait 90
```
+#### Route dampening
-```{cfgcmd} set protocols bgp parameters dampening re-use \<seconds\>
+When a route fails, a withdrawal update is sent across the network. When
+the route returns, an advertisement is sent. A route that repeatedly
+fails and returns (flaps) generates substantial protocol traffic.
-This command defines the accumulated penalty amount at which the
-route is re-advertised. The penalty range is 1 to 20000.
+Route dampening, described in
+[RFC 2439](https://datatracker.ietf.org/doc/html/rfc2439), identifies
+unstable routes and suppresses them. Each time a route flaps, it incurs a
+penalty (1000 per flap). When the accumulated penalty exceeds the
+suppress threshold, the router stops advertising the route.
+
+The penalty decays exponentially over time (halving every half-life
+interval). When it drops below the reuse threshold, the route is
+unsuppressed and becomes eligible for advertisement and use again. No
+route is suppressed indefinitely. The `max-suppress-time` is the upper
+bound on suppression duration.
+
+```{cfgcmd} set protocols bgp parameters dampening half-life \<1-45\>
+
+**Configure the route dampening half-life, in minutes.**
+
+This is the interval over which a route's accumulated penalty is halved.
```
+Example:
-```{cfgcmd} set protocols bgp parameters dampening start-suppress-time \<seconds\>
+```none
+set protocols bgp parameters dampening half-life 15
+```
-This command defines the accumulated penalty amount at which the
-route is suppressed. The penalty range is 1 to 20000.
+```{cfgcmd} set protocols bgp parameters dampening re-use \<1-20000\>
+
+**Configure the penalty threshold below which a suppressed route is
+reused.**
+
+Once the decaying penalty falls below this value, the route becomes
+eligible for use and is advertised to peers again.
+```
+
+Example:
+
+```none
+set protocols bgp parameters dampening re-use 750
```
+```{cfgcmd} set protocols bgp parameters dampening start-suppress-time \<1-20000\>
-```{cfgcmd} set protocols bgp parameters dampening max-suppress-time \<seconds\>
+**Configure the penalty threshold above which a route is suppressed.**
-This command defines the maximum time in minutes that a route is
-suppressed. The timer range is 1 to 255 minutes.
+Once a route's accumulated penalty exceeds this value, it is no longer
+advertised to peers or used locally until the penalty decays below the
+reuse threshold.
```
-#### Route Selection Configuration
+Example:
+
+```none
+set protocols bgp parameters dampening start-suppress-time 2000
+```
+
+```{cfgcmd} set protocols bgp parameters dampening max-suppress-time \<1-255\>
+
+**Configure the maximum time, in minutes, that a route may remain
+suppressed by dampening.**
+
+Once this limit is reached, the route becomes eligible for use and
+advertisement again, regardless of its remaining penalty.
+```
+
+Example:
+
+```none
+set protocols bgp parameters dampening max-suppress-time 60
+```
+
+#### Route selection configuration
```{cfgcmd} set protocols bgp parameters always-compare-med
- This command provides to compare the MED on routes, even when they were
- received from different neighbouring ASes. Setting this option makes the
- order of preference of routes more defined, and should eliminate MED
- induced oscillations.
+**Configure BGP to compare the MED attribute between routes received
+from different neighboring ASs during best-path selection.**
+
+By default, MED is only compared between routes received from the same
+neighboring AS.
+```
+
+```{note}
+Setting this option can make path selection more predictable, but it
+does not prevent MED-induced oscillation and can cause it in some
+topologies.
```
+Example:
+
+```none
+set protocols bgp parameters always-compare-med
+```
```{cfgcmd} set protocols bgp parameters bestpath as-path confed
-This command specifies that the length of confederation path sets and
-sequences should be taken into account during the BGP best path
-decision process.
+**Configure BGP to include the length of confederation path segments
+(AS_CONFED_SEQUENCE and AS_CONFED_SET) in the AS_PATH length used during
+best-path selection.**
+
+By default, these segments are not counted.
```
+Example:
+
+```none
+set protocols bgp parameters bestpath as-path confed
+```
```{cfgcmd} set protocols bgp parameters bestpath as-path multipath-relax
-This command specifies that BGP decision process should consider paths
-of equal AS_PATH length candidates for multipath computation. Without
-the knob, the entire AS_PATH must match for multipath computation.
+**Configure BGP to treat paths with equal AS_PATH length but different
+AS_PATH content as equal for load balancing.**
+
+Without this option, the entire AS_PATH content must match.
```
+Example:
+
+```none
+set protocols bgp parameters bestpath as-path multipath-relax
+```
```{cfgcmd} set protocols bgp parameters bestpath as-path ignore
-Ignore AS_PATH length when selecting a route
+**Configure BGP to ignore AS_PATH length entirely during best-path
+selection.**
```
+Example:
-```{cfgcmd} set protocols bgp parameters bestpath compare-routerid
+```none
+set protocols bgp parameters bestpath as-path ignore
+```
-Ensure that when comparing routes where both are equal on most metrics,
-including local-pref, AS_PATH length, IGP cost, MED, that the tie is
-broken based on router-ID.
+```{cfgcmd} set protocols bgp parameters bestpath compare-routerid
-If this option is enabled, then the already-selected check, where
-already selected eBGP routes are preferred, is skipped.
+**Configure BGP to use the lowest router ID as the tie-breaker between
+otherwise-equal eBGP routes, instead of the already-selected check.**
-If a route has an ORIGINATOR_ID attribute because it has been reflected,
-that ORIGINATOR_ID will be used. Otherwise, the router-ID of the peer
-the route was received from will be used.
+When this option is enabled, the already-selected check is skipped. If a
+route has been reflected (i.e., has an ORIGINATOR_ID attribute), that
+value is used. Otherwise, the router-ID of the peer that sent the route
+is used.
-The advantage of this is that the route-selection (at this point) will
-be more deterministic. The disadvantage is that a few or even one lowest-ID
-router may attract all traffic to otherwise-equal paths because of this
-check. It may increase the possibility of MED or IGP oscillation, unless
-other measures were taken to avoid these. The exact behaviour will be
-sensitive to the iBGP and reflection topology.
+The advantage is that route selection becomes more deterministic. The
+disadvantage is that a single low-ID router may attract traffic that
+would otherwise be spread across multiple equal-cost paths. The option
+can also increase the risk of MED- or IGP-induced oscillation. The exact
+behavior is sensitive to the iBGP and reflection topology.
```
+Example:
+
+```none
+set protocols bgp parameters bestpath compare-routerid
+```
```{cfgcmd} set protocols bgp parameters bestpath med confed
-This command specifies that BGP considers the MED when comparing routes
-originated from different sub-ASs within the confederation to which this
-BGP speaker belongs. The default state, where the MED attribute is not
-considered.
+**Configure BGP to consider the MED attribute when comparing routes
+received via different sub-ASs within the same BGP confederation.**
+
+By default, MED is only compared between routes received from the same
+sub-AS.
```
+Example:
+
+```none
+set protocols bgp parameters bestpath med confed
+```
```{cfgcmd} set protocols bgp parameters bestpath med missing-as-worst
-This command specifies that a route with a MED is always considered to be
-better than a route without a MED by causing the missing MED attribute to
-have a value of infinity. The default state, where the missing MED
-attribute is considered to have a value of zero.
+**Configure BGP to treat a missing MED attribute as the worst possible
+value during best-path selection.**
+
+By default, a missing MED is treated as 0, the best possible value.
```
+Example:
-```{cfgcmd} set protocols bgp parameters default local-pref <local-pref value>
+```none
+set protocols bgp parameters bestpath med missing-as-worst
+```
+
+```{cfgcmd} set protocols bgp parameters default local-pref \<0-4294967295\>
-This command specifies the default local preference value. The local
-preference range is 0 to 4294967295.
+**Configure the default LOCAL_PREF value assigned to eBGP-learned and
+locally-originated routes.**
+
+iBGP-learned routes always carry LOCAL_PREF and are not affected.
```
+Example:
+
+```none
+set protocols bgp parameters default local-pref 100
+```
```{cfgcmd} set protocols bgp parameters deterministic-med
-This command provides to compare different MED values that advertised by
-neighbours in the same AS for routes selection. When this command is
-enabled, routes from the same autonomous system are grouped together, and
-the best entries of each group are compared.
+**Configure BGP to group routes by the neighboring AS (the AS the route
+was received from) before comparing MED values during best-path
+selection.**
+
+When configured, BGP first selects the best route within each
+neighbor-AS group and then compares those per-AS bests.
```
+Example:
+
+```none
+set protocols bgp parameters deterministic-med
+```
```{cfgcmd} set protocols bgp address-family ipv4-unicast network \<prefix\> backdoor
-This command allows the router to prefer route to specified prefix learned
-via IGP through backdoor link instead of a route to the same prefix learned
-via EBGP.
+**Mark the specified IPv4 prefix as a backdoor route so that an IGP path
+to it is preferred over an eBGP-learned path.**
+```
+
+Example:
+
+```none
+set protocols bgp address-family ipv4-unicast network 198.51.100.0/24 backdoor
+```
+
+```{cfgcmd} set protocols bgp parameters bestpath bandwidth \<default-weight-for-missing | ignore | skip-missing\>
+
+**Configure how BGP uses the Link Bandwidth extended community in
+weighted-ECMP load balancing:**
+
+- `default-weight-for-missing`: Assigns a low default weight (1) to
+ paths that do not carry a link bandwidth attribute.
+- `ignore`: Disables weighted ECMP entirely and uses regular ECMP.
+- `skip-missing`: Excludes paths without link bandwidth from ECMP when
+ at least one other path carries it.
+```
+
+Example:
+
+```none
+set protocols bgp parameters bestpath bandwidth skip-missing
+```
+
+```{cfgcmd} set protocols bgp parameters bestpath peer-type multipath-relax
+
+**Configure BGP to allow load sharing across paths learned from
+different peer types (eBGP and iBGP) for the same destination.**
+
+Without this option, multipath is restricted to peers of the same type
+(eBGP-only or iBGP-only).
```
-#### Route Filtering Configuration
+Example:
-In order to control and modify routing information that is exchanged between
-peers you can use route-map, filter-list, prefix-list, distribute-list.
+```none
+set protocols bgp parameters bestpath peer-type multipath-relax
+```
-For inbound updates the order of preference is:
+```{cfgcmd} set protocols bgp parameters conditional-advertisement timer \<5-240\>
-> - route-map
-> - filter-list
-> - prefix-list, distribute-list
+**Configure the interval, in seconds, at which the BGP process
+re-evaluates `conditionally-advertise` conditions.**
-For outbound updates the order of preference is:
-> - prefix-list, distribute-list
-> - filter-list
-> - route-map
->
-> :::{note}
-> The attributes {cfgcmd}`prefix-list` and {cfgcmd}`distribute-list`
-> are mutually exclusive, and only one command (distribute-list or
-> prefix-list) can be applied to each inbound or outbound direction for a
-> particular neighbor.
-> :::
+The default is 60 seconds.
+```
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> distribute-list \<export|import\> \<number\>
+Example:
-This command applies the access list filters named in \<number\> to the
-specified BGP neighbor to restrict the routing information that BGP learns
-and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import`
-specify the direction in which the access list are applied.
+```none
+set protocols bgp parameters conditional-advertisement timer 30
```
+### Route filtering configuration
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> prefix-list \<export|import\> \<name\>
+To control and modify routing information exchanged between peers, you
+can use a `route-map`, `filter-list`, `prefix-list`, or `distribute-list`.
-This command applies the prfefix list filters named in \<name\> to the
-specified BGP neighbor to restrict the routing information that BGP learns
-and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import`
-specify the direction in which the prefix list are applied.
+Inbound updates are evaluated in the following order: `route-map`,
+`filter-list`, then either `prefix-list` or `distribute-list`. Outbound
+updates are evaluated in the following order: either `prefix-list` or
+`distribute-list`, `filter-list`, then `route-map`.
+
+```{note}
+`prefix-list` and `distribute-list` are mutually exclusive. Only one of
+the two can be applied to each inbound or outbound direction for a
+particular neighbor.
```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> distribute-list \<export | import\> \<1-65535\>
+
+**Apply the specified `access-list` to filter routing information received
+from or advertised to the specified peer.**
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> route-map \<export|import\> \<name\>
+`export` applies the filter to outbound advertisements, and `import`
+applies it to inbound updates.
+```
+
+Example:
-This command applies the route map named in \<name\> to the specified BGP
-neighbor to control and modify routing information that is exchanged
-between peers. The arguments {cfgcmd}`export` and {cfgcmd}`import`
-specify the direction in which the route map are applied.
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast distribute-list import 10
```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> prefix-list \<export | import\> \<name\>
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> filter-list \<export|import\> \<name\>
+**Apply the specified `prefix-list` to filter routing information received
+from or advertised to the specified peer.**
-This command applies the AS path access list filters named in \<name\> to the
-specified BGP neighbor to restrict the routing information that BGP learns
-and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import`
-specify the direction in which the AS path access list are applied.
+`export` applies the filter to outbound advertisements, and `import`
+applies it to inbound updates.
```
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast prefix-list import PEER-IN
+```
+
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> route-map \<export | import\> \<name\>
+
+**Apply the specified `route-map` to control and modify routing
+information received from or advertised to the specified peer.**
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> capability orf \<receive|send\>
+`export` applies the `route-map` to outbound advertisements, and `import`
+applies it to inbound updates.
+```
+
+Example:
-This command enables the ORF capability (described in {rfc}`5291`) on the
-local router, and enables ORF capability advertisement to the specified BGP
-peer. The {cfgcmd}`receive` keyword configures a router to advertise ORF
-receive capabilities. The {cfgcmd}`send` keyword configures a router to
-advertise ORF send capabilities. To advertise a filter from a sender, you
-must create an IP prefix list for the specified BGP peer applied in inbound
-derection.
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast route-map import PEER-IN
```
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> filter-list \<export | import\> \<name\>
-```{cfgcmd} set protocols bgp neighbor \<address|interface\> solo
+**Apply the specified AS-path access-list to filter routing information
+received from or advertised to the specified peer.**
-This command prevents from sending back prefixes learned from the neighbor.
+`export` applies the filter to outbound advertisements, and `import`
+applies it to inbound updates.
```
-#### BGP Scaling Configuration
+Example:
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast filter-list import AS-PATH-IN
+```
-BGP routers connected inside the same AS through BGP belong to an internal BGP
-session, or IBGP. In order to prevent routing table loops, IBGP speaker does
-not advertise IBGP-learned routes to other IBGP speaker (Split Horizon
-mechanism). As such, IBGP requires a full mesh of all peers. For large
-networks, this quickly becomes unscalable.
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> capability orf prefix-list \<receive | send\>
+**Enable the {abbr}`ORF (Outbound Route Filter)` capability on the
+local router and advertise it to the specified peer.**
-There are two ways that help us to mitigate the BGPs full-mesh requirement in
-a network:
+`receive` configures the router to accept ORF filters sent by the peer
+and use them to filter its own outbound updates. `send` configures the
+router to push its inbound prefix-list to the peer as an ORF, so the
+peer can filter its outbound updates before sending them.
+```
+
+```{note}
+To use the `send` option, an inbound prefix-list must already be
+configured for that peer on this router.
+```
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast capability orf prefix-list send
+```
-> - Using BGP route-reflectors
-> - Using BGP confederation
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> solo
+**Prevent the local BGP speaker from advertising prefixes learned from
+the specified neighbor back to that neighbor.**
+```
-##### Route Reflector Configuration
+Example:
+```none
+set protocols bgp neighbor 192.0.2.2 solo
+```
-Introducing route reflectors removes the need for the full-mesh. When you
-configure a route reflector you have to tell the router whether the other IBGP
-router is a client or non-client. A client is an IBGP router that the route
-reflector will “reflect” routes to, the non-client is just a regular IBGP
-neighbor. Route reflectors mechanism is described in {rfc}`4456` and updated
-by {rfc}`7606`.
+```{cfgcmd} set protocols bgp neighbor \<address | interface\> address-family \<ipv4-unicast | ipv6-unicast\> route-server-client
-```{cfgcmd} set protocols bgp neighbor \<address\> address-family \<ipv4-unicast|ipv6-unicast\> route-reflector-client
+**Configure the specified neighbor as a route-server client.**
-This command specifies the given neighbor as route reflector client.
+A route server, typically deployed at internet exchange points, peers
+with many participants and redistributes their routes between them
+while leaving AS_PATH, NEXT_HOP, and other BGP attributes untouched.
+Configuring a peer as `route-server-client` suppresses the standard
+eBGP outbound rewrites of these attributes for that peer.
```
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast route-server-client
+```
+
+### BGP scaling configuration
+
+Within an autonomous system (AS), BGP routers form iBGP sessions. To
+prevent routing loops, an iBGP speaker does not re-advertise iBGP-learned
+routes to other iBGP speakers. Consequently, iBGP requires a full mesh of
+sessions between all speakers, which scales poorly in large networks.
+
+The following mechanisms allow you to eliminate the need for a full iBGP
+mesh: route reflectors and confederations.
+
+#### Route reflector configuration
+
+{abbr}`RRs (Route Reflectors)` eliminate the need for a full iBGP mesh
+between clients.
+
+A route reflector treats its iBGP peers as either clients (whose routes
+are reflected to other clients and non-clients) or non-clients (regular
+iBGP peers, which still require a full mesh among themselves). The route
+reflector mechanism is described in
+[RFC 4456](https://datatracker.ietf.org/doc/html/rfc4456), with later
+refinements to error handling in
+[RFC 7606](https://datatracker.ietf.org/doc/html/rfc7606).
+
+```{cfgcmd} set protocols bgp neighbor \<address\> address-family \<ipv4-unicast | ipv6-unicast\> route-reflector-client
+
+**Configure the specified neighbor as a route-reflector client for the
+selected address family.**
+```
+
+Example:
+
+```none
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast route-reflector-client
+```
```{cfgcmd} set protocols bgp parameters cluster-id \<id\>
-This command specifies cluster ID which identifies a collection of route
-reflectors and their clients, and is used by route reflectors to avoid
-looping. By default cluster ID is set to the BGP router id value, but can be
-set to an arbitrary 32-bit value.
+**Configure the BGP cluster-ID used by route reflectors to identify a
+collection of reflectors and clients and to detect reflection loops.**
+
+By default, the cluster-ID is set to the BGP router-ID. It can be
+overridden with any 32-bit value in IPv4 address notation.
+```
+
+Example:
+
+```none
+set protocols bgp parameters cluster-id 192.0.2.10
+```
+
+```{cfgcmd} set protocols bgp parameters route-reflector-allow-outbound-policy
+
+**Allow outbound route-maps (and other outbound policy) to apply to
+routes the local route reflector reflects to its route reflector
+clients.**
+
+By default, FRR does not apply outbound policy to reflected routes, to
+preserve the reflector's transparency. Enabling this option allows
+outbound policy to take effect on reflected routes.
+```
+
+Example:
+
+```none
+set protocols bgp parameters route-reflector-allow-outbound-policy
```
-##### Confederation Configuration
+#### Confederation configuration
+
+A BGP confederation divides an AS into sub-ASs (member-ASs) to reduce the
+number of required iBGP peerings. Within each sub-AS, a full iBGP mesh is
+still required. Between sub-ASs, speakers use intra-confederation eBGP
+sessions that preserve iBGP-style handling of NEXT_HOP, LOCAL_PREF, and
+MED.
-A BGP confederation divides our AS into sub-ASes to reduce the number of
-required IBGP peerings. Within a sub-AS we still require full-mesh IBGP but
-between these sub-ASes we use something that looks like EBGP but behaves like
-IBGP (called confederation BGP). Confederation mechanism is described in
-{rfc}`5065`
+The confederation mechanism is described in
+[RFC 5065](https://datatracker.ietf.org/doc/html/rfc5065).
+
+```{cfgcmd} set protocols bgp parameters confederation identifier \<1-4294967294\>
+
+**Configure the externally visible BGP confederation identifier (the ASN
+that the entire confederation presents to other autonomous systems).**
+```
-```{cfgcmd} set protocols bgp parameters confederation identifier \<asn\>
+Example:
-This command specifies a BGP confederation identifier. \<asn\> is the number
-of the autonomous system that internally includes multiple sub-autonomous
-systems (a confederation).
+```none
+set protocols bgp parameters confederation identifier 65000
```
+```{cfgcmd} set protocols bgp parameters confederation peers \<1-4294967294\>
-```{cfgcmd} set protocols bgp parameters confederation peers \<nsubasn\>
+**Configure the ASNs of other (not local) sub-ASs within the same BGP
+confederation.**
+
+This command is multi-value: issue it once per remote sub-AS to add each
+member-AS to the confederation peer list. The local sub-AS (configured
+via `system-as`) must not be listed here.
+```
-This command sets other confederations \<nsubasn\> as members of autonomous
-system specified by {cfgcmd}`confederation identifier <asn>`.
+Example:
+
+```none
+set protocols bgp parameters confederation peers 65001
+set protocols bgp parameters confederation peers 65002
+set protocols bgp parameters confederation peers 65003
```
-## Operational Mode Commands
+## Operation
+
### Show
-```{opcmd} show bgp \<ipv4|ipv6\>
+```{opcmd} show bgp \<ipv4 | ipv6\>
- This command displays all entries in BGP routing table.
+**Show the BGP routing table for the specified address family.**
```
+Example output:
```none
-BGP table version is 10, local router ID is 10.0.35.3, vrf id 0
-Default local pref 100, local AS 65000
+BGP table version is 10, local router ID is 192.0.2.3, vrf id 0
+Default local pref 100, local AS 64496
Status codes: s suppressed, d damped, h history, * valid, > best, = multipath,
i internal, r RIB-failure, S Stale, R Removed
Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self
Origin codes: i - IGP, e - EGP, ? - incomplete
RPKI validation codes: V valid, I invalid, N Not found
-
Network Next Hop Metric LocPrf Weight Path
-*> 198.51.100.0/24 10.0.34.4 0 0 65004 i
-*> 203.0.113.0/24 10.0.35.5 0 0 65005 i
-
+*> 198.51.100.0/24 192.0.2.4 0 0 64500 i
+*> 203.0.113.0/24 192.0.2.5 0 0 64501 i
Displayed 2 routes and 2 total paths
```
+```{opcmd} show bgp \<ipv4 | ipv6\> \<address | prefix\>
-```{opcmd} show bgp \<ipv4|ipv6\> \<address|prefix\>
-
-This command displays information about the particular entry in the BGP
-routing table.
+**Show detailed BGP information for the specified prefix.**
```
+Example output:
```none
BGP routing table entry for 198.51.100.0/24
Paths: (1 available, best #1, table default)
Advertised to non peer-group peers:
- 10.0.13.1 10.0.23.2 10.0.34.4 10.0.35.5
- 65004
- 10.0.34.4 from 10.0.34.4 (10.0.34.4)
+ 192.0.2.1 192.0.2.2 192.0.2.4 192.0.2.5
+ 64504
+ 192.0.2.4 from 192.0.2.4 (192.0.2.4)
Origin IGP, metric 0, valid, external, best (First path received)
Last update: Wed Jan 6 12:18:53 2021
```
-
```{opcmd} show bgp cidr-only
-This command displays routes with classless interdomain routing (CIDR).
+**Show BGP routes with non-natural (non-classful) prefix lengths.**
```
+```{opcmd} show bgp \<ipv4 | ipv6\> community \<value\>
-```{opcmd} show bgp \<ipv4|ipv6\> community \<value\>
+**Show BGP routes carrying the specified community value in their
+COMMUNITIES attribute.**
-This command displays routes that belong to specified BGP communities.
-Valid value is a community number in the range from 1 to 4294967200,
-or AA:NN (autonomous system-community number/2-byte number), no-export,
-local-as, or no-advertise.
-```
+Valid values are:
+- a decimal number (1-4294967200)
+- an `AA:NN` pair, where `AA` is an autonomous system number, and `NN`
+ is a 2-byte community value (e.g., `65001:100`)
+- one of the well-known community names, such as `no-export`,
+ `no-advertise`, or `local-as`.
+```
-```{opcmd} show bgp \<ipv4|ipv6\> community-list \<name\>
+```{opcmd} show bgp \<ipv4 | ipv6\> community-list \<name\>
-This command displays routes that are permitted by the BGP
-community list.
+**Show BGP routes permitted by the specified community-list.**
```
+```{opcmd} show bgp \<ipv4 | ipv6\> dampening dampened-paths
-```{opcmd} show bgp \<ipv4|ipv6\> dampening dampened-paths
-
-This command displays BGP dampened routes.
+**Show BGP routes currently suppressed by dampening.**
```
+```{opcmd} show bgp \<ipv4 | ipv6\> dampening flap-statistics
-```{opcmd} show bgp \<ipv4|ipv6\> dampening flap-statistics
-
-This command displays information about flapping BGP routes.
+**Show flap statistics for BGP routes tracked by dampening (any route
+with an accumulated penalty).**
```
+```{opcmd} show bgp \<ipv4 | ipv6\> filter-list \<name\>
-```{opcmd} show bgp \<ipv4|ipv6\> filter-list \<name\>
-
-This command displays BGP routes allowed by the specified AS Path
-access list.
+**Show BGP routes permitted by the specified AS-path access-list.**
```
+```{opcmd} show bgp \<ipv4 | ipv6\> neighbors \<address\> advertised-routes
-```{opcmd} show bgp \<ipv4|ipv6\> neighbors \<address\> advertised-routes
-
-This command displays BGP routes advertised to a neighbor.
+**Show the BGP routes advertised by the local router to the specified
+neighbor.**
```
+```{opcmd} show bgp \<ipv4 | ipv6\> neighbors \<address\> received-routes
-```{opcmd} show bgp \<ipv4|ipv6\> neighbors \<address\> received-routes
+**Show the BGP routes received from the specified neighbor before the
+inbound policy is applied.**
-This command displays BGP routes originating from the specified BGP
-neighbor before inbound policy is applied. To use this command inbound
-soft reconfiguration must be enabled.
+Requires inbound `soft-reconfiguration` to be enabled for that neighbor
+on the local router.
```
+```{opcmd} show bgp \<ipv4 | ipv6\> neighbors \<address\> routes
-```{opcmd} show bgp \<ipv4|ipv6\> neighbors \<address\> routes
-
-This command displays BGP received-routes that are accepted after filtering.
+**Show the BGP routes received from the specified neighbor that were
+accepted after inbound filtering.**
```
+```{opcmd} show bgp \<ipv4 | ipv6\> neighbors \<address\> dampened-routes
-```{opcmd} show bgp \<ipv4|ipv6\> neighbors \<address\> dampened-routes
-
-This command displays dampened routes received from BGP neighbor.
+**Show dampened BGP routes received from the specified neighbor.**
```
+```{opcmd} show bgp \<ipv4 | ipv6\> regexp \<text\>
-```{opcmd} show bgp \<ipv4|ipv6\> regexp \<text\>
-
-This command displays information about BGP routes whose AS path
-matches the specified regular expression.
+**Show BGP routes whose AS_PATH matches the specified regular
+expression.**
```
+```{opcmd} show bgp \<ipv4 | ipv6\> summary
-```{opcmd} show bgp \<ipv4|ipv6\> summary
-
-This command displays the status of all BGP connections.
+**Show a summary of all BGP sessions.**
```
+Example output:
```none
IPv4 Unicast Summary:
-BGP router identifier 10.0.35.3, local AS number 65000 vrf-id 0
+BGP router identifier 192.0.2.3, local AS number 64500 vrf-id 0
BGP table version 11
RIB entries 5, using 920 bytes of memory
Peers 4, using 82 KiB of memory
Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd
-10.0.13.1 4 65000 148 159 0 0 0 02:16:01 0
-10.0.23.2 4 65000 136 143 0 0 0 02:13:21 0
-10.0.34.4 4 65004 161 163 0 0 0 02:16:01 1
-10.0.35.5 4 65005 162 166 0 0 0 02:16:01 1
+192.0.2.1 4 64500 148 159 0 0 0 02:16:01 0
+192.0.2.2 4 64500 136 143 0 0 0 02:13:21 0
+192.0.2.4 4 64504 161 163 0 0 0 02:16:01 1
+192.0.2.5 4 64505 162 166 0 0 0 02:16:01 1
Total number of neighbors 4
```
### Reset
-```{opcmd} reset bgp \<ipv4|ipv6\> \<address\> [soft [in|out]]
+```{opcmd} reset bgp \<ipv4 | ipv6\> \<address\> [soft [in | out]]
-This command resets BGP connections to the specified neighbor IP address.
-With argument {cfgcmd}`soft` this command initiates a soft reset. If
-you do not specify the {cfgcmd}`in` or {cfgcmd}`out` options, both
-inbound and outbound soft reconfiguration are triggered.
-```
+**Reset the BGP session with the specified neighbor.**
+With `soft`, the router performs a soft reset rather than tearing down
+the TCP session. Without `in` or `out`, soft reset is applied in both
+directions.
+```
```{opcmd} reset bgp all
-This command resets all BGP connections of given router.
+**Reset all BGP sessions on this router.**
```
+```{opcmd} reset bgp \<ipv4 | ipv6\> external
-```{opcmd} reset bgp \<ipv4|ipv6\> external
-
-This command resets all external BGP peers of given router.
+**Reset all external (eBGP) sessions on this router for the specified
+address family.**
```
+```{opcmd} reset bgp \<ipv4 | ipv6\> peer-group \<name\> [soft [in | out]]
-```{opcmd} reset bgp \<ipv4|ipv6\> peer-group \<name\> [soft [in|out]]
+**Reset BGP sessions with all members of the specified peer group.**
-This command resets BGP connections to the specified peer group.
-With argument {cfgcmd}`soft` this command initiates a soft reset. If
-you do not specify the {cfgcmd}`in` or {cfgcmd}`out` options, both
-inbound and outbound soft reconfiguration are triggered.
+With `soft`, the router performs a soft reset rather than tearing down
+the TCP sessions. Without `in` or `out`, soft reset is applied in both
+directions.
```
## Examples
+
### IPv4 peering
-A simple eBGP configuration:
+The following example demonstrates a simple eBGP peering between two VyOS
+routers.
**Node 1:**
```none
-set protocols bgp system-as 65534
-set protocols bgp neighbor 192.168.0.2 ebgp-multihop '2'
-set protocols bgp neighbor 192.168.0.2 remote-as '65535'
-set protocols bgp neighbor 192.168.0.2 update-source '192.168.0.1'
-set protocols bgp neighbor 192.168.0.2 address-family ipv4-unicast
-set protocols bgp address-family ipv4-unicast network '172.16.0.0/16'
-set protocols bgp parameters router-id '192.168.0.1'
+set protocols bgp system-as 64512
+set protocols bgp neighbor 192.0.2.2 ebgp-multihop '2'
+set protocols bgp neighbor 192.0.2.2 remote-as '64513'
+set protocols bgp neighbor 192.0.2.2 update-source '192.0.2.1'
+set protocols bgp neighbor 192.0.2.2 address-family ipv4-unicast
+set protocols bgp address-family ipv4-unicast network '198.51.100.0/24'
+set protocols bgp parameters router-id '192.0.2.1'
```
**Node 2:**
```none
-set protocols bgp system-as 65535
-set protocols bgp neighbor 192.168.0.1 ebgp-multihop '2'
-set protocols bgp neighbor 192.168.0.1 remote-as '65534'
-set protocols bgp neighbor 192.168.0.1 update-source '192.168.0.2'
-set protocols bgp neighbor 192.168.0.1 address-family ipv4-unicast
-set protocols bgp address-family ipv4-unicast network '172.17.0.0/16'
-set protocols bgp parameters router-id '192.168.0.2'
+set protocols bgp system-as 64513
+set protocols bgp neighbor 192.0.2.1 ebgp-multihop '2'
+set protocols bgp neighbor 192.0.2.1 remote-as '64512'
+set protocols bgp neighbor 192.0.2.1 update-source '192.0.2.2'
+set protocols bgp neighbor 192.0.2.1 address-family ipv4-unicast
+set protocols bgp address-family ipv4-unicast network '203.0.113.0/24'
+set protocols bgp parameters router-id '192.0.2.2'
```
-Don't forget, the CIDR declared in the network statement MUST **exist in your
-routing table (dynamic or static), the best way to make sure that is true is
-creating a static route:**
+The CIDR declared in the `network` statement must exist in the routing
+table (either dynamic or static). The simplest way to ensure that is to
+create a blackhole static route:
**Node 1:**
```none
-set protocols static route 172.16.0.0/16 blackhole distance '254'
+set protocols static route 198.51.100.0/24 blackhole distance '254'
```
**Node 2:**
```none
-set protocols static route 172.17.0.0/16 blackhole distance '254'
+set protocols static route 203.0.113.0/24 blackhole distance '254'
```
### IPv6 peering
-A simple BGP configuration via IPv6.
+The following example demonstrates a simple eBGP peering over IPv6.
**Node 1:**
```none
-set protocols bgp system-as 65534
+set protocols bgp system-as 64512
set protocols bgp neighbor 2001:db8::2 ebgp-multihop '2'
-set protocols bgp neighbor 2001:db8::2 remote-as '65535'
+set protocols bgp neighbor 2001:db8::2 remote-as '64513'
set protocols bgp neighbor 2001:db8::2 update-source '2001:db8::1'
set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast
set protocols bgp address-family ipv6-unicast network '2001:db8:1::/48'
-set protocols bgp parameters router-id '10.1.1.1'
+set protocols bgp parameters router-id '192.0.2.1'
```
**Node 2:**
```none
-set protocols bgp system-as 65535
+set protocols bgp system-as 64513
set protocols bgp neighbor 2001:db8::1 ebgp-multihop '2'
-set protocols bgp neighbor 2001:db8::1 remote-as '65534'
+set protocols bgp neighbor 2001:db8::1 remote-as '64512'
set protocols bgp neighbor 2001:db8::1 update-source '2001:db8::2'
set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast
set protocols bgp address-family ipv6-unicast network '2001:db8:2::/48'
-set protocols bgp parameters router-id '10.1.1.2'
+set protocols bgp parameters router-id '192.0.2.2'
```
-Don't forget, the CIDR declared in the network statement **MUST exist in your
-routing table (dynamic or static), the best way to make sure that is true is
-creating a static route:**
+As with IPv4, the prefix declared in the `network` statement must exist
+in the routing table. A blackhole static route is the simplest way to
+ensure this:
**Node 1:**
@@ -1416,65 +2818,70 @@ set protocols static route6 2001:db8:1::/48 blackhole distance '254'
set protocols static route6 2001:db8:2::/48 blackhole distance '254'
```
-### Route Filtering
+### Route filtering
-Route filter can be applied using a route-map:
+The following example applies inbound and outbound route filters to both
+IPv4 and IPv6 BGP sessions using route-maps that reference prefix-lists.
-**Node1:**
+**Node 1:**
```none
-set policy prefix-list AS65535-IN rule 10 action 'permit'
-set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16'
-set policy prefix-list AS65535-OUT rule 10 action 'deny'
-set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16'
-set policy prefix-list6 AS65535-IN rule 10 action 'permit'
-set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48'
-set policy prefix-list6 AS65535-OUT rule 10 action 'deny'
-set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48'
-
-set policy route-map AS65535-IN rule 10 action 'permit'
-set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN'
-set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN'
-set policy route-map AS65535-IN rule 20 action 'deny'
-set policy route-map AS65535-OUT rule 10 action 'deny'
-set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT'
-set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT'
-set policy route-map AS65535-OUT rule 20 action 'permit'
-
-set protocols bgp system-as 65534
-set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map export 'AS65535-OUT'
-set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map import 'AS65535-IN'
-set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map export 'AS65535-OUT'
-set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map import 'AS65535-IN'
+set policy prefix-list AS64513-IN rule 10 action 'permit'
+set policy prefix-list AS64513-IN rule 10 prefix '203.0.113.0/24'
+set policy prefix-list AS64513-OUT rule 10 action 'permit'
+set policy prefix-list AS64513-OUT rule 10 prefix '198.51.100.0/24'
+set policy prefix-list6 AS64513-IN rule 10 action 'permit'
+set policy prefix-list6 AS64513-IN rule 10 prefix '2001:db8:2::/48'
+set policy prefix-list6 AS64513-OUT rule 10 action 'permit'
+set policy prefix-list6 AS64513-OUT rule 10 prefix '2001:db8:1::/48'
+
+set policy route-map AS64513-IN rule 10 action 'permit'
+set policy route-map AS64513-IN rule 10 match ip address prefix-list 'AS64513-IN'
+set policy route-map AS64513-IN rule 20 action 'permit'
+set policy route-map AS64513-IN rule 20 match ipv6 address prefix-list 'AS64513-IN'
+set policy route-map AS64513-IN rule 30 action 'deny'
+set policy route-map AS64513-OUT rule 10 action 'permit'
+set policy route-map AS64513-OUT rule 10 match ip address prefix-list 'AS64513-OUT'
+set policy route-map AS64513-OUT rule 20 action 'permit'
+set policy route-map AS64513-OUT rule 20 match ipv6 address prefix-list 'AS64513-OUT'
+set policy route-map AS64513-OUT rule 30 action 'deny'
+
+set protocols bgp system-as 64512
+set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map export 'AS64513-OUT'
+set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map import 'AS64513-IN'
+set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map export 'AS64513-OUT'
+set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map import 'AS64513-IN'
```
-**Node2:**
+**Node 2:**
```none
-set policy prefix-list AS65534-IN rule 10 action 'permit'
-set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16'
-set policy prefix-list AS65534-OUT rule 10 action 'deny'
-set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16'
-set policy prefix-list6 AS65534-IN rule 10 action 'permit'
-set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48'
-set policy prefix-list6 AS65534-OUT rule 10 action 'deny'
-set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48'
-
-set policy route-map AS65534-IN rule 10 action 'permit'
-set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN'
-set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN'
-set policy route-map AS65534-IN rule 20 action 'deny'
-set policy route-map AS65534-OUT rule 10 action 'deny'
-set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT'
-set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT'
-set policy route-map AS65534-OUT rule 20 action 'permit'
-
-set protocols bgp system-as 65535
-set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map export 'AS65534-OUT'
-set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map import 'AS65534-IN'
-set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map export 'AS65534-OUT'
-set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map import 'AS65534-IN'
-```
-
-We could expand on this and also deny link local and multicast in the rule 20
-action deny.
+set policy prefix-list AS64512-IN rule 10 action 'permit'
+set policy prefix-list AS64512-IN rule 10 prefix '198.51.100.0/24'
+set policy prefix-list AS64512-OUT rule 10 action 'permit'
+set policy prefix-list AS64512-OUT rule 10 prefix '203.0.113.0/24'
+set policy prefix-list6 AS64512-IN rule 10 action 'permit'
+set policy prefix-list6 AS64512-IN rule 10 prefix '2001:db8:1::/48'
+set policy prefix-list6 AS64512-OUT rule 10 action 'permit'
+set policy prefix-list6 AS64512-OUT rule 10 prefix '2001:db8:2::/48'
+
+set policy route-map AS64512-IN rule 10 action 'permit'
+set policy route-map AS64512-IN rule 10 match ip address prefix-list 'AS64512-IN'
+set policy route-map AS64512-IN rule 20 action 'permit'
+set policy route-map AS64512-IN rule 20 match ipv6 address prefix-list 'AS64512-IN'
+set policy route-map AS64512-IN rule 30 action 'deny'
+set policy route-map AS64512-OUT rule 10 action 'permit'
+set policy route-map AS64512-OUT rule 10 match ip address prefix-list 'AS64512-OUT'
+set policy route-map AS64512-OUT rule 20 action 'permit'
+set policy route-map AS64512-OUT rule 20 match ipv6 address prefix-list 'AS64512-OUT'
+set policy route-map AS64512-OUT rule 30 action 'deny'
+
+set protocols bgp system-as 64513
+set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map export 'AS64512-OUT'
+set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map import 'AS64512-IN'
+set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map export 'AS64512-OUT'
+set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map import 'AS64512-IN'
+```
+
+This pattern can be extended in the `rule 30` deny clauses to also
+filter link-local and multicast prefixes.
diff --git a/docs/configuration/service/lldp.md b/docs/configuration/service/lldp.md
index 7fdba6c8..c555376a 100644
--- a/docs/configuration/service/lldp.md
+++ b/docs/configuration/service/lldp.md
@@ -1,154 +1,270 @@
+---
+myst:
+ html_meta:
+ description: |
+ LLDP is a vendor-neutral Layer 2 protocol that lets devices
+ advertise their identity, capabilities, and management addresses
+ to directly connected neighbors and learn the same from them.
+ keywords: lldp, lldp-med, cdp, edp, fdp, sonmp, neighbor-discovery
+---
+
(lldp)=
# LLDP
-{abbr}`LLDP (Link Layer Discovery Protocol)` is a vendor-neutral link layer
-protocol in the Internet Protocol Suite used by network devices for advertising
-their identity, capabilities, and neighbors on an IEEE 802 local area network,
-principally wired Ethernet. The protocol is formally referred to by the IEEE
-as Station and Media Access Control Connectivity Discovery specified in IEEE
-802.1AB and IEEE 802.3-2012 section 6 clause 79.
-
-LLDP performs functions similar to several proprietary protocols, such as
-{abbr}`CDP (Cisco Discovery Protocol)`,
-{abbr}`FDP (Foundry Discovery Protocol)`,
-{abbr}`NDP (Nortel Discovery Protocol)` and {abbr}`LLTD (Link Layer Topology
-Discovery)`.
-
-Information gathered with LLDP is stored in the device as a {abbr}`MIB
-(Management Information Database)` and can be queried with {abbr}`SNMP (Simple
-Network Management Protocol)` as specified in {rfc}`2922`. The topology of an
-LLDP-enabled network can be discovered by crawling the hosts and querying this
-database. Information that may be retrieved include:
-
-- System Name and Description
+{abbr}`LLDP (Link Layer Discovery Protocol)` is a vendor-neutral Layer
+2 protocol that enables devices to advertise their identity,
+capabilities, and management addresses to directly connected neighbors
+and to learn the same information from them. LLDP is specified in IEEE
+802.1AB, Station and Media Access Control Connectivity Discovery.
+
+Each device sends LLDP frames periodically on every interface where
+LLDP transmission is enabled and records the received information in a
+local neighbor database. This database can also be queried with
+{abbr}`SNMP (Simple Network Management Protocol)` (see `set service
+lldp snmp`), so the topology of an entire LLDP-enabled network can be
+mapped by querying each device in turn. Advertised information may
+include:
+
+- System name and description
- Port name and description
- VLAN name
-- IP management address
-- System capabilities (switching, routing, etc.)
-- MAC/PHY information
-- MDI power
-- Link aggregation
+- Management IP address
+- System capabilities (the device's role: router, bridge, telephone,
+ and so on)
+- Physical link settings, such as speed, duplex, and auto-negotiation
+ (MAC/PHY)
+- Power over Ethernet (MDI power)
+- Link aggregation (bonding)
+
+LLDP provides functionality similar to proprietary protocols such as
+{abbr}`CDP (Cisco Discovery Protocol)`,
+{abbr}`EDP (Extreme Discovery Protocol)`,
+{abbr}`FDP (Foundry Discovery Protocol)`, and
+{abbr}`SONMP (SynOptics Network Management Protocol)`. You can
+configure VyOS to interoperate with devices running these protocols
+via `set service lldp legacy-protocols`.
## Configuration
```{cfgcmd} set service lldp
-Enable LLDP service
+**Enable the LLDP service.**
+
+With no further configuration, the service sends and processes LLDP
+frames on every available local interface.
+
+Configure `service lldp interface` to restrict it to selected
+interfaces.
```
-```{cfgcmd} set service lldp management-address \<address\>
+Example:
-Define IPv4/IPv6 management address transmitted via LLDP. Multiple addresses
-can be defined. Only addresses connected to the system will be transmitted.
+```none
+set service lldp
```
```{cfgcmd} set service lldp interface \<interface\>
-Enable transmission of LLDP information on given \<interface\>. You can also
-say ``all`` here so LLDP is turned on on every interface.
+**Enable LLDP on the specified interface.**
+
+Repeat the command to enable LLDP on multiple interfaces. The special
+value `all` enables LLDP on every available local interface.
+
+Once LLDP is enabled with `set service lldp`, it runs on all available
+local interfaces by default. Configuring one or more interfaces here
+limits LLDP strictly to those configured, disabling LLDP on all
+remaining interfaces.
+```
+
+Example:
+
+```none
+set service lldp interface eth1
+set service lldp interface eth2
+```
+
+```{cfgcmd} set service lldp interface \<interface\> mode \<disable | rx-tx | tx | rx\>
+
+**Configure the LLDP administrative status on the specified
+interface:**
+
+- `rx-tx`: Sends LLDP frames and processes received ones.
+- `rx`: Processes only received frames, so the router learns about its
+ neighbors without announcing itself.
+- `tx`: Sends frames only.
+- `disable`: Neither sends nor processes frames on the interface.
+
+The default is `rx-tx`.
```
-```{cfgcmd} set service lldp interface \<interface\> mode [disable|rx-tx|rx|tx]
+Example:
-Configure the administrative status of the given port.
+```none
+set service lldp interface eth1 mode rx
+```
+
+```{cfgcmd} set service lldp interface \<interface\> location coordinate-based latitude \<latitude\>
+
+**Configure the latitude of the coordinate-based LLDP-MED location
+advertised on the specified interface.**
+
+The value is a decimal number followed by N or S. Both latitude and
+longitude must be configured.
+```
+
+Example:
+
+```none
+set service lldp interface eth1 location coordinate-based latitude 37.524449N
+```
+
+```{cfgcmd} set service lldp interface \<interface\> location coordinate-based longitude \<longitude\>
+
+**Configure the longitude of the coordinate-based LLDP-MED location
+advertised on the specified interface.**
+
+The value is a decimal number followed by E or W. Both latitude and
+longitude must be configured.
+```
+
+Example:
+
+```none
+set service lldp interface eth1 location coordinate-based longitude 122.267255W
+```
+
+```{cfgcmd} set service lldp interface \<interface\> location coordinate-based altitude \<altitude\>
+
+**Configure the altitude, in meters, of the coordinate-based LLDP-MED
+location advertised on the specified interface.**
+
+The value is a positive or negative number of meters, where 0 means no
+altitude. Altitude is part of the coordinate-based location, so
+latitude and longitude must also be configured for it to be
+advertised.
+
+The default is 0.
+```
-By default, all ports are configured to be in rx-tx mode. This means they
-can receive and transmit LLDP frames.
+Example:
-In rx mode, they won't emit any frames. In tx mode, they won't receive
-any frames. In disabled mode, no frame will be sent and any incoming frame
-will be discarded.
+```none
+set service lldp interface eth1 location coordinate-based altitude 12
+```
+
+```{cfgcmd} set service lldp interface \<interface\> location coordinate-based datum \<WGS84 | NAD83 | MLLW\>
+
+**Configure the geodetic datum of the coordinate-based LLDP-MED
+location advertised on the specified interface:**
+
+- `WGS84` and `NAD83` select the corresponding geodetic datum.
+- `MLLW` selects NAD83 combined with the
+ {abbr}`MLLW (Mean Lower Low Water)` tidal datum, used where altitude
+ is referenced to tidal water level.
+
+The default is `WGS84`.
+```
+
+Example:
+
+```none
+set service lldp interface eth1 location coordinate-based datum NAD83
+```
+
+```{cfgcmd} set service lldp interface \<interface\> location elin \<number\>
+
+**Advertise an Emergency Call Service
+{abbr}`ELIN (Emergency Location Identification Number)` on the
+specified interface.**
+
+The value is 10 to 25 digits.
+```
+
+Example:
+
+```none
+set service lldp interface eth1 location elin 1234567890
+```
+
+```{cfgcmd} set service lldp management-address \<address\>
+
+**Advertise the specified IPv4 or IPv6 address to LLDP neighbors as a
+management address.**
+
+Repeat the command to advertise multiple addresses. VyOS generates a
+warning upon commit if the address is a loopback address or is not
+assigned to any interface.
+```
+
+Example:
+
+```none
+set service lldp management-address 192.0.2.1
+set service lldp management-address 2001:db8::1
```
```{cfgcmd} set service lldp snmp
-Enable SNMP queries of the LLDP database
+**Allow the LLDP database to be queried over SNMP.**
+
+Requires a configured SNMP service (see {ref}`snmp`). Otherwise, the
+commit fails.
```
-```{cfgcmd} set service lldp legacy-protocols \<cdp|edp|fdp|sonmp\>
+Example:
-Enable given legacy protocol on this LLDP instance. Legacy protocols include:
-* ``cdp`` - Listen for CDP for Cisco routers/switches
-* ``edp`` - Listen for EDP for Extreme routers/switches
-* ``fdp`` - Listen for FDP for Foundry routers/switches
-* ``sonmp`` - Listen for SONMP for Nortel routers/switches
+```none
+set service lldp snmp
```
+```{cfgcmd} set service lldp legacy-protocols \<cdp | edp | fdp | sonmp\>
-## Operation
+**Enable the LLDP service to process the specified vendor-proprietary
+discovery protocol:**
-```{opcmd} show lldp neighbors
+- `cdp`: Cisco routers and switches.
+- `edp`: Extreme routers and switches.
+- `fdp`: Foundry routers and switches.
+- `sonmp`: Nortel routers and switches.
-Displays information about all neighbors discovered via LLDP.
+After receiving a frame of an enabled protocol on an interface, VyOS
+also transmits that protocol on the interface.
-:::{code-block} none
-vyos@vyos:~$ show lldp neighbors
-Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station
- D - Docsis, T - Telephone, O - Other
+Repeat the command to enable processing of multiple protocols.
+```
-Device ID Local Proto Cap Platform Port ID
---------- ----- ----- --- -------- -------
-BR2.vyos.net eth0 LLDP R VyOS 1.2.4 eth1
-BR3.vyos.net eth0 LLDP RB VyOS 1.2.4 eth2
-SW1.vyos.net eth0 LLDP B Cisco IOS Software GigabitEthernet0/6
-:::
+Example:
+
+```none
+set service lldp legacy-protocols cdp
+```
+
+## Operation
+
+```{opcmd} show lldp neighbors
+
+**Show all neighbors discovered via LLDP or enabled legacy
+protocols.**
```
```{opcmd} show lldp neighbors detail
-Get detailed information about LLDP neighbors.
-
-:::{code-block} none
-vyos@vyos:~$ show lldp neighbors detail
--------------------------------------------------------------------------------
-LLDP neighbors:
--------------------------------------------------------------------------------
-Interface: eth0, via: LLDP, RID: 28, Time: 0 day, 00:24:33
-Chassis:
- ChassisID: mac 00:53:00:01:02:c9
- SysName: BR2.vyos.net
- SysDescr: VyOS 1.3-rolling-201912230217
- MgmtIP: 192.0.2.1
- MgmtIP: 2001:db8::ffff
- Capability: Bridge, on
- Capability: Router, on
- Capability: Wlan, off
- Capability: Station, off
-Port:
- PortID: mac 00:53:00:01:02:c9
- PortDescr: eth0
- TTL: 120
- PMD autoneg: supported: no, enabled: no
- MAU oper type: 10GigBaseCX4 - X copper over 8 pair 100-Ohm balanced cable
-VLAN: 201 eth0.201
-VLAN: 205 eth0.205
-LLDP-MED:
- Device Type: Network Connectivity Device
- Capability: Capabilities, yes
- Capability: Policy, yes
- Capability: Location, yes
- Capability: MDI/PSE, yes
- Capability: MDI/PD, yes
- Capability: Inventory, yes
- Inventory:
- Hardware Revision: None
- Software Revision: 4.19.89-amd64-vyos
- Firmware Revision: 6.00
- Serial Number: VMware-42 1d 83 b9 fe c1 bd b2-7
- Manufacturer: VMware, Inc.
- Model: VMware Virtual Platform
- Asset ID: No Asset Tag
--------------------------------------------------------------------------------
-:::
+**Show detailed information about discovered neighbors.**
```
```{opcmd} show lldp neighbors interface \<interface\>
-Show LLDP neighbors connected via interface \<interface\>.
+**Show neighbors discovered on the specified interface.**
+```
+
+```{opcmd} show lldp neighbors interface \<interface\> detail
+
+**Show detailed information about neighbors discovered on the
+specified interface.**
```
```{opcmd} show log lldp
-Used for troubleshooting.
-``` \ No newline at end of file
+**Show the log of the LLDP service since the last boot.**
+```
diff --git a/docs/configuration/system/ipv6.md b/docs/configuration/system/ipv6.md
index ee0a6ade..71409e4e 100644
--- a/docs/configuration/system/ipv6.md
+++ b/docs/configuration/system/ipv6.md
@@ -1,193 +1,444 @@
+---
+myst:
+ html_meta:
+ description: |
+ The `system ipv6` subtree provides IPv6 settings that apply to the
+ whole router, such as packet forwarding, the neighbor cache,
+ Duplicate Address Detection, and ECMP multipath hashing. It also
+ controls route installation filtering and next hop tracking.
+ keywords: ipv6, neighbor cache, dad, ecmp, multipath, next hop tracking
+---
+
+(ipv6)=
+
# IPv6
-## System configuration commands
+The `system ipv6` subtree provides IPv6 settings that apply to the whole router.
+
+To configure IPv6 settings for an individual interface, use
+`set interfaces <type> <name> ipv6`.
+
+## Configuration
+
+### Forwarding
```{cfgcmd} set system ipv6 disable-forwarding
- Use this command to disable IPv6 forwarding on all interfaces.
+**Disable IPv6 forwarding between the router's interfaces.**
+
+By default, the router forwards IPv6 packets between interfaces.
```
+Example:
+
+```none
+set system ipv6 disable-forwarding
+```
+
+### Neighbor cache
+
+The neighbor cache stores mappings between each neighbor's IPv6 and
+link-layer addresses, together with the neighbor's reachability state.
+The router learns these entries dynamically as it communicates with
+neighbors.
+
+```{cfgcmd} set system ipv6 neighbor table-size \<1024 | 2048 | 4096 | 8192 | 16384 | 32768\>
+
+**Configure the maximum number of dynamically learned entries in the
+neighbor cache.**
+
+The default is 8192.
+
+This limit counts only the entries that the router learns dynamically.
+It does not count entries added manually as permanent, nor entries
+that another subsystem installs and maintains.
+
+The router derives two more thresholds from this number. Once the
+neighbor cache reaches half of this number, the router removes
+entries older than 5 seconds. While the neighbor cache holds fewer
+than one eighth of this number, the router does not remove entries
+to reclaim space.
+
+The command also sets the following kernel parameters:
+
+- `net.ipv6.neigh.default.gc_thresh3`: Takes the value of the configured
+ maximum number.
+- `net.ipv6.neigh.default.gc_thresh2`: Takes half of that number.
+- `net.ipv6.neigh.default.gc_thresh1`: Takes one eighth of that number.
+
+If `system sysctl parameter` sets any of these parameters, the `system
+sysctl` values take precedence.
+```
-```{cfgcmd} set system ipv6 neighbor table-size \<number\>
+Example:
-Use this command to define the maximum number of entries to keep in
-the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768).
+```none
+set system ipv6 neighbor table-size 16384
```
+### Duplicate address detection
```{cfgcmd} set system ipv6 strict-dad
-Use this command to disable IPv6 operation on interface when
-Duplicate Address Detection fails on Link-Local address.
+**Disable IPv6 on any interface where {abbr}`DAD (Duplicate Address
+Detection)` detects a duplicate of the interface's MAC-based link-local
+address.**
+
+Without this command, a duplicate MAC-based link-local address does not
+disable IPv6 on the interface.
+
+When the router disables IPv6 on an interface this way, the router does
+not re-enable IPv6 on that interface automatically.
+```
+
+Example:
+
+```none
+set system ipv6 strict-dad
```
+### Multipath routing
```{cfgcmd} set system ipv6 multipath layer4-hashing
-Use this command to user Layer 4 information for ECMP hashing.
+**Include Layer 4 information in the
+{abbr}`ECMP (Equal-Cost Multi-Path)` hash.**
+
+By default, the router hashes the source and destination addresses, the
+protocol number, and the flow label.
+
+With this command, the router hashes the source and destination addresses,
+the protocol number, and the source and destination port numbers instead,
+so it distributes the flows between two hosts by port rather than by flow
+label.
```
-### Zebra/Kernel route filtering
+Example:
+
+```none
+set system ipv6 multipath layer4-hashing
+```
+### Route installation filtering
-Zebra supports prefix-lists and Route Maps to match routes received from
-other FRR components. The permit/deny facilities provided by these commands
-can be used to filter which routes zebra will install in the kernel.
+The router can apply a `route-map` to filter a routing protocol's
+routes before installing them in the router's {abbr}`FIB (Forwarding
+Information Base)`.
-```{cfgcmd} set system ipv6 protocol \<protocol\> route-map \<route-map\>
+```{cfgcmd} set system ipv6 protocol \<any | babel | bgp | isis | ospfv3 | ripng | static\> route-map \<name\>
-Apply a route-map filter to routes for the specified protocol. The following
-protocols can be used: any, babel, bgp, isis, ospfv3, ripng, static
+**Filter the routes of the specified protocol before the router installs
+them in the FIB.**
-:::{note}
-If you choose any as the option that will cause all protocols that
-are sending routes to zebra.
-:::
+The router evaluates the `route-map` for each next hop of a route and
+does not install a next hop that the `route-map` denies.
+
+A `route-map` configured for a specific protocol applies to that
+protocol instead of the `route-map` configured under `protocol any`. The
+router never applies both.
+
+This command applies to the default {abbr}`VRF (Virtual Routing and
+Forwarding)`. Use `vrf name <name> ipv6 protocol <protocol> route-map
+<name>` for another VRF.
+
+The `route-map` must exist under `policy route-map`. Otherwise, the
+commit fails.
```
-### Nexthop Tracking
+Example:
+
+```none
+set system ipv6 protocol ospfv3 route-map OSPFV3-SRC
+```
+### Next hop tracking
-Nexthop tracking resolve nexthops via the default route by default. This is enabled
-by default for a traditional profile of FRR which we use. It and can be disabled if
-you do not want to e.g. allow BGP to peer across the default route.
+Next hop tracking lets a routing protocol, such as BGP, learn whether a
+route's next hop is reachable through the router's {abbr}`RIB (Routing
+Information Base)`.
```{cfgcmd} set system ipv6 nht no-resolve-via-default
-Do not allow IPv6 nexthop tracking to resolve via the default route. This
-parameter is configured per-VRF, so the command is also available in the VRF
-subnode.
-```
+**Prevent IPv6 next hop tracking from resolving next hops through the
+default route.**
-## Operational commands
+By default, next hop tracking considers a next hop reachable when only
+the default route covers it. This command makes next hop tracking
+require a more specific route.
+The default applies to the `traditional` profile of `system frr
+profile`, which is the default profile. With the `datacenter` profile,
+next hop tracking does not resolve next hops through the default route,
+so this command has no effect under that profile.
-### Show commands
+This command applies to the default VRF. Use `vrf name <name> ipv6 nht
+no-resolve-via-default` for another VRF.
+```
-```{opcmd} show ipv6 neighbors
+Example:
-Use this command to show IPv6 Neighbor Discovery Protocol information.
+```none
+set system ipv6 nht no-resolve-via-default
```
+## Operation
+
+### Show
+
+```{opcmd} show ipv6 forwarding
+
+**Show the router's IPv6 forwarding status.**
+```
```{opcmd} show ipv6 groups
-Use this command to show IPv6 multicast group membership.
+**Show the router's active IPv6 network connections and its IPv6
+multicast group memberships per interface.**
```
+```{opcmd} show ipv6 multicast group
-```{opcmd} show ipv6 forwarding
+**Show the IPv6 multicast group memberships of the router's
+interfaces, as a table sorted by interface.**
+```
+
+```{opcmd} show ipv6 multicast group interface \<interface\>
+
+**Show the IPv6 multicast group memberships of the specified interface.**
+```
+
+```{opcmd} show ipv6 neighbors
+
+**Show the router's neighbor cache.**
+```
+
+```{opcmd} show ipv6 neighbors interface \<interface\>
+
+**Show the neighbor cache entries on the specified interface.**
+```
-Use this command to show IPv6 forwarding status.
+```{opcmd} show ipv6 neighbors state \<reachable | stale | failed | permanent\>
+
+**Show the neighbor cache entries in the specified state.**
```
+```{opcmd} show ipv6 nht
+
+**Show the IPv6 next hop tracking table.**
+```
+
+```{opcmd} show ipv6 nht vrf \<name | default | all\>
+
+**Show the IPv6 next hop tracking table for the specified VRF, or for
+all VRFs.**
+```
```{opcmd} show ipv6 route
-Use this command to show IPv6 routes.
-
-Check the many parameters available for the show ipv6 route command:
-
-:::{code-block} none
-vyos@vyos:~$ show ipv6 route
-Possible completions:
- <Enter> Execute the current command
- <X:X::X:X> Show IPv6 routes of given address or prefix
- <X:X::X:X/M>
- bgp Show IPv6 BGP routes
- cache Show kernel IPv6 route cache
- connected Show IPv6 connected routes
- forward Show kernel IPv6 route table
- isis Show IPv6 ISIS routes
- kernel Show IPv6 kernel routes
- ospfv3 Show IPv6 OSPF6 routes
- ripng Show IPv6 RIPNG routes
- static Show IPv6 static routes
- summary Show IPv6 routes summary
- table Show IP routes in policy table
- tag Show only routes with tag
- vrf Show IPv6 routes in VRF
-:::
+**Show the IPv6 routes in the router's RIB.**
+```
+
+```{opcmd} show ipv6 route \<kernel | connected | static | ripng | ospfv3 | isis | bgp | openfabric\>
+
+**Show only the IPv6 routes from the given source.**
+```
+
+```{opcmd} show ipv6 route \<address | prefix\>
+
+**Show the IPv6 routes in the RIB for the specified address or prefix.**
+
+For an address, the router shows the routes for the most specific prefix
+that covers the address. For a prefix, the router shows only the routes
+for exactly that prefix.
+```
+
+```{opcmd} show ipv6 route \<prefix\> longer-prefixes
+
+**Show the IPv6 routes for the specified prefix and for all more specific
+prefixes within it.**
+```
+
+```{opcmd} show ipv6 route forward
+
+**Show the IPv6 routes in the kernel's main routing table.**
+```
+
+```{opcmd} show ipv6 route forward \<address | prefix\>
+
+**Show the IPv6 routes in the kernel's main routing table that exactly
+match the specified address or prefix.**
+```
+
+```{opcmd} show ipv6 route summary
+
+**Show the number of IPv6 routes from each source.**
+
+For each source, the output shows the number of routes in the RIB and
+the number of those routes installed in the FIB. BGP routes are counted
+separately for eBGP and iBGP.
+```
+
+```{opcmd} show ipv6 route summary table \<tableid\>
+
+**Show the number of IPv6 routes from each source in the specified
+routing table.**
+```
+
+```{opcmd} show ipv6 route table \<tableid\>
+
+**Show the IPv6 routes in the specified routing table.**
+```
+
+```{opcmd} show ipv6 route tag \<tag\>
+
+**Show the IPv6 routes with the specified tag.**
```
+
+```{opcmd} show ipv6 route vrf \<name | all\>
+
+**Show the IPv6 routes in the RIB of the specified VRF, or of all VRFs.**
+```
+
+```{opcmd} show ipv6 route vrf \<name | all\> \<connected | static | kernel | bgp | ospfv3 | ripng | isis\>
+
+**Show the IPv6 routes from the given source in the specified VRF, or
+in all VRFs.**
+```
+
+```{opcmd} show ipv6 route vrf \<name | all\> \<address | prefix\>
+
+**Show the IPv6 routes for the given address or prefix in the
+specified VRF, or in all VRFs.**
+```
+
+```{opcmd} show ipv6 route vrf \<name | all\> \<prefix\> longer-prefixes
+
+**Show the IPv6 routes for the specified prefix and for all more
+specific prefixes within it in the specified VRF, or in all VRFs.**
+```
+
+```{opcmd} show ipv6 route vrf \<name | all\> summary
+
+**Show the number of IPv6 routes from each source in the specified
+VRF, or in all VRFs.**
+
+For each source, the output shows the number of routes in the RIB and
+the number of those routes installed in the FIB. BGP routes are counted
+separately for eBGP and iBGP.
+```
+
+```{opcmd} show ipv6 route vrf \<name | all\> tag \<tag\>
+
+**Show the IPv6 routes with the specified tag in the specified VRF, or
+in all VRFs.**
+```
+
```{opcmd} show ipv6 prefix-list
- Use this command to show all IPv6 prefix lists
+**Show all IPv6 prefix lists configured on the router.**
+```
- There are different parameters for getting prefix-list information:
+```{opcmd} show ipv6 prefix-list \<name\>
- :::{code-block} none
- vyos@vyos:~$ show ipv6 prefix-list
- Possible completions:
- <Enter> Execute the current command
- <WORD> Show specified IPv6 prefix-list
- detail Show detail of IPv6 prefix-lists
- summary Show summary of IPv6 prefix-lists
- :::
+**Show the specified IPv6 prefix list.**
```
+```{opcmd} show ipv6 prefix-list detail
-```{opcmd} show ipv6 access-list
+**Show all IPv6 prefix lists configured on the router, with details
+for each list and each entry.**
+```
+
+```{opcmd} show ipv6 prefix-list detail \<name\>
-Use this command to show all IPv6 access lists
+**Show the specified IPv6 prefix list, with details for the list and
+each entry.**
+```
-You can also specify which IPv6 access-list should be shown:
+```{opcmd} show ipv6 prefix-list summary
-:::{code-block} none
-vyos@vyos:~$ show ipv6 access-list
-Possible completions:
- <Enter> Execute the current command
- <text> Show specified IPv6 access-list
-:::
+**Show all IPv6 prefix lists configured on the router, with the entry
+count and sequence range of each list but without the entries.**
```
-```{opcmd} show ipv6 ospfv3
- Use this command to get information about OSPFv3.
+```{opcmd} show ipv6 prefix-list summary \<name\>
- You can get more specific OSPFv3 information by using the parameters
- shown below:
+**Show the specified IPv6 prefix list, with its entry count and
+sequence range but without the entries.**
+```
- :::{code-block} none
- vyos@vyos:~$ show ipv6 ospfv3
- Possible completions:
- <Enter> Execute the current command
- area Show OSPFv3 spf-tree information
- border-routers
- Show OSPFv3 border-router (ABR and ASBR) information
- database Show OSPFv3 Link state database information
- interface Show OSPFv3 interface information
- linkstate Show OSPFv3 linkstate routing information
- neighbor Show OSPFv3 neighbor information
- redistribute Show OSPFv3 redistribute External information
- route Show OSPFv3 routing table information
- :::
+```{opcmd} show ipv6 prefix-list \<name\> \<prefix\>
+
+**Show the entry of the specified IPv6 prefix list that matches the
+specified prefix.**
+```
+
+```{opcmd} show ipv6 prefix-list \<name\> \<prefix\> first-match
+
+**Show the first entry of the specified IPv6 prefix list that matches
+the specified prefix.**
```
+```{opcmd} show ipv6 prefix-list \<name\> \<prefix\> longer
-```{opcmd} show ipv6 ripng
+**Show the entries of the specified IPv6 prefix list whose prefix is
+equal to or more specific than the specified prefix.**
+```
+
+```{opcmd} show ipv6 prefix-list \<name\> seq \<number\>
-Use this command to get information about the RIPNG protocol
+**Show the entry with the given sequence number in the specified IPv6
+prefix list.**
```
+```{opcmd} show ipv6 access-list
+
+**Show all IPv6 access lists configured on the router.**
+```
-```{opcmd} show ipv6 ripng status
+```{opcmd} show ipv6 access-list \<name\>
-Use this command to show the status of the RIPNG protocol
+**Show the specified IPv6 access list.**
```
-### Reset commands
+### Reset
-```{opcmd} reset bgp ipv6 \<address\>
+```{opcmd} reset ipv6 neighbors address \<address\>
-Use this command to clear Border Gateway Protocol statistics or
-status.
+**Reset the neighbor cache entry for the specified IPv6 address.**
```
-```{opcmd} reset ipv6 neighbors \<address | interface\>
-Use this command to reset IPv6 Neighbor Discovery Protocol cache for
-an address or interface.
+```{opcmd} reset ipv6 neighbors interface \<interface\>
+
+**Reset the neighbor cache entries on the specified interface.**
```
+
```{opcmd} reset ipv6 route cache
-Use this command to flush the kernel IPv6 route cache.
-An address can be added to flush it only for that route.
-``` \ No newline at end of file
+**Reset the entire IPv6 kernel route cache.**
+```
+
+```{opcmd} reset ipv6 route cache \<address | prefix\>
+
+**Reset the IPv6 kernel route cache entries for the specified address
+or prefix.**
+```
+
+### Clear
+
+```{opcmd} clear ipv6 prefix-list
+
+**Reset the hit counts of all entries in all IPv6 prefix lists.**
+```
+
+```{opcmd} clear ipv6 prefix-list \<name\>
+
+**Reset the hit counts of all entries in the specified IPv6 prefix
+list.**
+```
+
+```{opcmd} clear ipv6 prefix-list \<name\> \<prefix\>
+
+**Reset the hit counts of the entries in the specified IPv6 prefix list
+whose prefix is equal to or less specific than the specified prefix.**
+```
diff --git a/docs/configuration/system/option.md b/docs/configuration/system/option.md
index ed1c3461..ecb3853b 100644
--- a/docs/configuration/system/option.md
+++ b/docs/configuration/system/option.md
@@ -97,6 +97,91 @@ embedded serial console interfaces to speed up the boot process.
```
+### Kernel crash dump (kdump)
+
+kdump is a kernel crash dumping mechanism that captures the contents of
+system memory when a kernel panic occurs. The capture is performed by a
+second, minimal kernel (the capture kernel) that is loaded into a reserved
+memory region at boot time. When the main kernel panics, the capture kernel
+runs and saves the memory image (vmcore) to disk for later analysis.
+
+:::{note}
+kdump requires VyOS to be installed to disk. It is not available in
+live-boot mode.
+:::
+
+:::{note}
+Changes to kdump settings take effect only after a system reboot.
+:::
+
+#### Configuration
+
+```{cfgcmd} set system option kdump memory \<size | auto\>
+
+**Reserve memory for the kdump capture kernel in megabytes.**
+
+The size can be specified in the next format:
+a single amount (e.g., `512`).
+
+Setting this option to `auto` (default) applies
+the following reservations:
+
+:::{list-table}
+:header-rows: 1
+
+* - **System RAM**
+ - **Reserved memory**
+ - **Notes**
+* - less than 1 GB
+ - 0 MB
+ - On systems with less than 1 GB of RAM, `auto` reserves no memory
+ and kdump is not active. Set an explicit size to enable kdump on
+ such systems.
+* - 1 GB – 8 GB
+ - 512 MB
+ -
+* - 8 GB – 64 GB
+ - 768 MB
+ -
+* - 64 GB and above
+ - 1 GB
+ -
+:::
+```
+Example:
+```none
+set system option kdump memory 512
+set system option kdump memory auto
+```
+
+```{cfgcmd} set system option kdump dump-path \<path\>
+
+**Configure the directory where crash dumps (vmcore files) are saved
+after a panic.**
+The path must be absolute (begin with `/`).
+
+Defaults to `/var/crash`.
+```
+Example:
+```none
+set system option kdump dump-path /var/log/kdump
+```
+
+#### Operation
+
+```{opcmd} show system kdump
+
+Display the kdump service operational status and configuration summary.
+```
+
+```{opcmd} show system kdump dumps
+
+List all recorded kernel crash dumps under the configured dump path.
+Each entry shows the dump directory, combined size (vmcore + dmesg) and
+capture timestamp.
+```
+
+
## HTTP client
```{cfgcmd} set system option http-client source-address \<address\>
diff --git a/docs/installation/virtual/docker.md b/docs/installation/virtual/docker.md
index 3489b94a..6d980066 100644
--- a/docs/installation/virtual/docker.md
+++ b/docs/installation/virtual/docker.md
@@ -1,10 +1,10 @@
---
-lastproofread: '2026-02-02'
+lastproofread: '2026-08-30'
---
(docker)=
-# Run VyOS in a Docker Container
+# Run VyOS as a container
Docker is an open-source project for deploying applications as standardized
units called containers. Deploying VyOS in a container provides a simple and
@@ -14,8 +14,9 @@ workloads.
## IPv6 support for Docker
VyOS requires an IPv6-enabled Docker network. Currently Linux distributions
-do not enable Docker IPv6 support by default. You can enable IPv6 support in
-two ways.
+do not enable Docker IPv6 support by default.
+
+You can enable IPv6 support in two ways.
### Method 1: Create a docker network with IPv6 support
@@ -25,7 +26,6 @@ Here's an example using the `macvlan` driver.
docker network create --ipv6 -d macvlan -o parent=eth0 --subnet 2001:db8::/64 --subnet 192.0.2.0/24 mynet
```
-
### Method 2: Add IPv6 support to the Docker daemon
Edit /etc/docker/daemon.json to set the `ipv6` key to `true` and specify
@@ -47,26 +47,61 @@ $ sudo systemctl reload docker
## Deploy container from ISO
-Download the ISO you want to base the container on. In this example,
-the ISO is `vyos-1.4-rolling-202308240020-amd64.iso`. If you
-created a custom IPv6-enabled network, include it as the `--net` parameter
-to `docker run`.
+A VyOS ISO image can be converted into an OCI (Open Container Initiative)
+image using the `iso-to-oci` helper script from the
+[vyos-build](https://github.com/vyos/vyos-build) repository. The script
+extracts the root filesystem from the ISO, removes components which are not
+usable inside a container (kernel, firmware, and the corresponding CLI nodes),
+and generates a tarball which can be imported by Docker.
+
+The script requires `xorriso`, `squashfs-tools` and `jq` to be installed. All
+of them are already present in the vyos-build container.
+
+### Build a container image from a locally built ISO
+
+If you build your own ISO from source (see {ref}`build`), the `oci` make
+target converts the ISO which is generated in `build/` in one step:
+
+```none
+$ make oci
+I: extracting ISO metadata
+I: extracting squashfs image
+I: extracting squashfs content
+I: generate OCI container image vyos-1.5.1-oci-amd64.tar
+I: to import the previously generated OCI image to your local images run:
+
+ docker import vyos-1.5.1-oci-amd64.tar vyos:1.5.1 --change 'CMD ["/sbin/init"]'
+```
+
+### Build a container image from a downloaded ISO
+
+To use a released or nightly ISO instead, call the script directly and pass
+the path to the ISO image:
+
+```none
+$ git clone https://github.com/vyos/vyos-build.git
+$ ./vyos-build/scripts/iso-to-oci vyos-1.5.1-generic-amd64.iso
+```
+
+### Import and run the container
+
+Import the generated tarball as a local image and start the container. If you
+created a custom IPv6-enabled network, include it as the `--net` parameter to
+`docker run`.
```none
-$ mkdir vyos && cd vyos
-$ curl -o vyos-1.4-rolling-202308240020-amd64.iso https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.4-rolling-202308240020/vyos-1.4-rolling-202308240020-amd64.iso
-$ mkdir rootfs
-$ sudo mount -o loop vyos-1.4-rolling-202308240020-amd64.iso rootfs
-$ sudo apt-get install -y squashfs-tools
-$ mkdir unsquashfs
-$ sudo unsquashfs -f -d unsquashfs/ rootfs/live/filesystem.squashfs
-$ sudo tar -C unsquashfs -c . | docker import - vyos:1.4-rolling-202111281249
-$ sudo umount rootfs
-$ cd ..
-$ sudo rm -rf vyos
+$ docker import vyos-1.5.1-oci-amd64.tar vyos:1.5.1 \
+> --change 'CMD ["/sbin/init"]'
$ docker run -d --rm --name vyos --privileged -v /lib/modules:/lib/modules \
-> vyos:1.4-rolling-202111281249 /sbin/init
+> vyos:1.5.1
$ docker exec -ti vyos su - vyos
```
To stop the container, run `docker stop vyos`.
+
+:::{hint}
+The very same image can also be used with
+[Containerlab](https://containerlab.dev) to build virtual network labs. Refer
+to its [VyOS kind](https://containerlab.dev/manual/kinds/vyosnetworks_vyos/)
+documentation for the required node settings.
+:::
diff --git a/docs/vpp/configuration/dataplane/cpu.md b/docs/vpp/configuration/dataplane/cpu.md
index d92f6587..bd67b91e 100644
--- a/docs/vpp/configuration/dataplane/cpu.md
+++ b/docs/vpp/configuration/dataplane/cpu.md
@@ -35,6 +35,27 @@ This parameter defines the total number of CPU cores allocated to VPP.
```{cfgcmd} set vpp settings resource-allocation cpu-cores \<core-number\>
```
+:::{important}
+`cpu-cores` requires at least the same number of CPUs to be isolated from the
+kernel scheduler with `set system option kernel cpu isolate-cpus`. VPP takes
+its main core and its worker cores from the isolated set, and the commit is
+rejected when fewer CPUs are isolated than requested:
+
+```none
+Not enough isolated CPU cores available: 2 requested, but only 0 isolated.
+To isolate CPUs please use command
+"set system option kernel cpu isolate-cpus ..." save and reboot!
+```
+
+This applies even when `cpu-cores` is left at its default of `1`. VPP always
+takes its main core from the isolated set, so at least one CPU has to be
+isolated before the dataplane can be enabled at all.
+
+CPU isolation is a kernel option, so it has to be committed, saved and applied
+with a reboot **before** VPP is configured — the two cannot be set in the same
+commit. See {ref}`Optimal Configuration Example <vpp-config-setup-order>`.
+:::
+
The system automatically assigns cores using the following rules:
> - The first two CPU cores are always reserved for the operating system and
diff --git a/docs/vpp/configuration/dataplane/system.md b/docs/vpp/configuration/dataplane/system.md
index 51ee8f54..7ece3192 100644
--- a/docs/vpp/configuration/dataplane/system.md
+++ b/docs/vpp/configuration/dataplane/system.md
@@ -190,9 +190,24 @@ Disables all optional CPU mitigations for security vulnerabilities
platforms.
```
+(vpp-config-setup-order)=
+
### Optimal Configuration Example
-For a system with 4 CPU cores (0-3) where cores 2-3 are dedicated to VPP:
+For a system with 4 CPU cores (0-3) where cores 2-3 are dedicated to VPP.
+
+:::{important}
+Kernel options and VPP settings **cannot be applied in the same commit**.
+
+Everything under `system option kernel` only takes effect after a reboot,
+while the VPP configuration is validated against the *running* kernel. VPP is
+also committed before `system option`, so within a single commit the kernel
+options are never in place yet and the VPP part is rejected.
+
+Configure the kernel options first, save, reboot, and only then configure VPP.
+:::
+
+**Step 1 — kernel options**
```none
# Kernel CPU optimizations
@@ -201,12 +216,50 @@ set system option kernel cpu isolate-cpus '2-3'
set system option kernel cpu nohz-full '2-3'
set system option kernel cpu rcu-no-cbs '2-3'
+# Hugepages
+set system option kernel memory hugepage-size 2M hugepage-count '2048'
+
# System optimizations
set system option kernel disable-hpet
set system option kernel disable-mce
set system option kernel disable-power-saving
set system option kernel disable-softlockup
+```
+
+Commit, save and reboot:
+
+```none
+commit
+save
+exit
+reboot
+```
+
+**Step 2 — VPP configuration, after the reboot**
+```none
# VPP CPU assignment
set vpp settings resource-allocation cpu-cores '2'
+
+# Interfaces to attach to the dataplane
+set vpp settings interface eth0
+set vpp settings interface eth1
```
+
+```none
+commit
+save
+```
+
+:::{note}
+If the VPP part is committed too early, the commit fails with a message such
+as `Not enough free memory to start VPP!` or `Not enough isolated CPU cores
+available`, both of which point back at `set system option kernel ...`. That
+means the reboot from step 1 has not happened yet.
+
+Note that such a commit is *partial*: the `system option kernel` part is still
+applied even though the commit is reported as failed. The `set vpp ...`
+statements stay in the configuration session, but they are neither applied nor
+written by `save`, which writes the *running* configuration. They are lost on
+the reboot and have to be entered again.
+:::
diff --git a/docs/vpp/requirements.md b/docs/vpp/requirements.md
index 159f70d4..db53058a 100644
--- a/docs/vpp/requirements.md
+++ b/docs/vpp/requirements.md
@@ -52,6 +52,23 @@ prerequisites before enabling VPP:
- Recommended: 16 GB or more (especially for high throughput, many interfaces,
or large routing tables).
+- **Kernel Configuration**
+
+ Besides the hardware itself, VPP needs hugepages and isolated CPU cores.
+ Both are configured under `system option kernel` and only take effect after
+ a reboot, while VPP validates them against the *running* kernel.
+
+ :::{important}
+ The kernel options and the VPP configuration cannot be applied in the same
+ commit. Configure them under `system option kernel` first, `commit`, `save`
+ and reboot, and only then configure VPP.
+ :::
+
+ :::{seealso}
+ {ref}`VyOS Configuration for VPP <vpp_config_system>` — hugepages, CPU
+ isolation and kernel tuning, with a worked example of both steps.
+ :::
+
- **Network Interface Cards (NICs)**
:::{warning}
@@ -102,6 +119,13 @@ prerequisites before enabling VPP:
* - PCI ID
- 1af4:1000
- Red Hat, Inc. Virtio network device
+ (legacy ID)
+ - KVM-based hypervisors, including with
+ Open vSwitch; Google Cloud
+ * - PCI ID
+ - 1af4:1041
+ - Red Hat, Inc. Virtio network device
+ (modern ID)
- KVM-based hypervisors, including with
Open vSwitch; Google Cloud
* - PCI ID
@@ -125,7 +149,9 @@ prerequisites before enabling VPP:
```
:::{note}
- This option bypasses the hardware validation checks for the specified
- devices. Stability and performance are not guaranteed when using
- unsupported NICs or drivers.
+ This option is a single global switch, not a per-device one: it bypasses
+ the hardware validation check for every interface attached to VPP, not
+ only for the one that needed it, and for interfaces attached later as
+ well. Stability and performance are not guaranteed when using unsupported
+ NICs or drivers.
:::
generated by cgit v1.2.3 (git 2.39.1) at 2026-10-15 04:18:22 +0000