From 791282079d1c2ec0af8fa12ed40932ff1e225f2f Mon Sep 17 00:00:00 2001 From: Chris Date: Mon, 11 May 2026 16:18:09 -0400 Subject: [PATCH 1/5] adding documentation for show bgp output I95-61467 --- docs/config_bgp.md | 145 +++++++++++++++++++++++++++++++++++++++++++ docusaurus.config.js | 5 +- 2 files changed, 146 insertions(+), 4 deletions(-) diff --git a/docs/config_bgp.md b/docs/config_bgp.md index 1a5a0f2450..8d1147e59b 100644 --- a/docs/config_bgp.md +++ b/docs/config_bgp.md @@ -1037,3 +1037,148 @@ admin@branchoffice1.seattlesite1 (routing-protocol[type=bgp])# confederation mem admin@branchoffice1.seattlesite1 (routing-protocol[type=bgp])# confederation member-as 2200 admin@branchoffice1.seattlesite1 (routing-protocol[type=bgp])# exit ``` + +## Viewing Filtered BGP Routes + +When an inbound BGP policy rejects prefixes received from a neighbor, those routes do not appear in the BGP table or the FIB. The `filtered-routes` option exposes exactly which prefixes were suppressed by the inbound policy for a given neighbor, making it straightforward to troubleshoot why expected routes are absent from the routing table. + +:::note +This feature is available in SSR version 7.2.0-r1 and above. +::: + +### PCLI + +The `filtered-routes` option is available as a third choice alongside `received-routes` and `advertised-routes` in the `show bgp neighbors` command: + +``` +show bgp neighbors [vrf ] filtered-routes [ipv4 | ipv4-vpn | ipv6 | ipv6-vpn] +``` + +**Examples** + +Display filtered routes for a neighbor in the default VRF using IPv4 unicast (the default address family): + +```text +admin@router1.site1# show bgp neighbors 172.16.3.3 filtered-routes +``` + +Display filtered IPv6 routes for a neighbor in a named VRF: + +```text +admin@router1.site1# show bgp neighbors vrf vrfA fd00:5::3 filtered-routes ipv6 +``` + +When no routes have been filtered, the command returns an empty table. When routes are present, the output format mirrors that of `received-routes` and `advertised-routes`. If the neighbor address is unknown, the VRF does not exist, or the address family is invalid, the PCLI surfaces the underlying vty error string describing the problem. + +### REST API + +A new endpoint mirrors the PCLI functionality: + +``` +GET /api/v1/routing/bgp/neighbors/filtered-routes +``` + +**Query Parameters** + +| Parameter | Required | Default | Description | +|---|---|---|---| +| `neighborAddress` | Yes | — | IP address of the BGP neighbor | +| `vrf` | No | `default` | VRF name | +| `addressFamily` | No | `ipv4` | Address family: `ipv4`, `ipv4-vpn`, `ipv6`, or `ipv6-vpn` | +| `firstIndex` | No | `0` | Zero-based starting index for paginated results | +| `elementCount` | No | all | Maximum number of routes to return (range: 1–5000) | + +:::note +The REST endpoint does not support `vrf all` or `addressFamily all`. Each VRF and address family must be queried individually. +::: + +**Example: IPv4, default VRF** + +```bash +curl --unix-socket /var/run/128technology/speakeasy.sock -i -XGET \ + 'http://localhost/api/v1/routing/bgp/neighbors/filtered-routes?neighborAddress=172.16.3.3&firstIndex=0&elementCount=1' +``` + +Response: + +```json +{ + "bgpTableVersion": 14, + "bgpLocalRouterId": "2.1.1.1", + "defaultLocPrf": 100, + "localAS": 2, + "bgpStatusCodes": { + "suppressed": "s", "damped": "d", "history": "h", + "valid": "*", "best": ">", "multipath": "=", + "internal": "i", "ribFailure": "r", "stale": "S", "removed": "R" + }, + "bgpOriginCodes": { "igp": "i", "egp": "e", "incomplete": "?" }, + "filteredRoutes": [ + { + "prefix": "10.99.1.0/24", + "network": "10.99.1.0/24", + "nextHop": "172.16.3.2", + "metric": 0, + "weight": 0, + "path": "3", + "bgpOriginCode": "?", + "valid": true, + "best": true + } + ], + "totalPrefixCounter": 1, + "filteredPrefixCounter": 0, + "nextEntry": 1 +} +``` + +**Example: IPv6, named VRF** + +```bash +curl --unix-socket /var/run/128technology/speakeasy.sock -i -XGET \ + 'http://localhost/api/v1/routing/bgp/neighbors/filtered-routes?neighborAddress=fd00:5::3&firstIndex=0&elementCount=1&addressFamily=ipv6&vrf=vrfA' +``` + +Response: + +```json +{ + "bgpTableVersion": 1, + "bgpLocalRouterId": "2.1.1.1", + "defaultLocPrf": 100, + "localAS": 2, + "filteredRoutes": [ + { + "prefix": "2001:db8:5::1/128", + "network": "2001:db8:5::1/128", + "nextHopGlobal": "fd00:5::3", + "metric": 0, + "weight": 0, + "path": "3", + "bgpOriginCode": "?", + "valid": true, + "best": true + } + ], + "totalPrefixCounter": 1, + "filteredPrefixCounter": 0, + "nextEntry": 1 +} +``` + +### Troubleshooting + +| Failure | PCLI behavior | REST behavior | +|---|---|---| +| `bgpd` not running | Surfaces vty error string | Returns standard upstream failure with informative status code | +| Unknown neighbor IP, neighbor not in specified VRF/address family | Surfaces vty error string with neighbor details | Returns `200 OK` with a `warning` key in the JSON body | +| Invalid `addressFamily` or `vrf` argument | Surfaces vty error string | Returns `200 OK` with a `warning` key in the JSON body | +| vty call timeout (120 s) | Surfaces timeout error string | Returns `HTTP 400` with timeout exception message | + +PCLI and REST activity is logged in `routingManager.log`. FRR vty-level logs are in `routingEngine.log`. + +### Version History + +| Release | Modification | +|---|---| +| 7.2.0 | Feature introduced. | diff --git a/docusaurus.config.js b/docusaurus.config.js index 1959f84cd3..06ad758ec6 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -7,12 +7,9 @@ module.exports = { organizationName: '128technology', // Usually your GitHub org/user name. projectName: 'docs', // Usually your repo name. onBrokenAnchors: 'throw', + onBrokenMarkdownLinks: 'throw', markdown: { mermaid: true, - hooks: { - onBrokenMarkdownLinks: 'throw', - onBrokenMarkdownImages: 'throw', - }, }, themes: ['@docusaurus/theme-mermaid'], themeConfig: { From fda99575cb04047725685f4dd57448ef194be26e Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 12 May 2026 14:19:34 -0400 Subject: [PATCH 2/5] adding AES-GCM content for 7.2 Swift beta 1. --- docs/config_bgp.md | 2 +- docs/sec_security_policy.md | 51 +++++++++++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+), 1 deletion(-) diff --git a/docs/config_bgp.md b/docs/config_bgp.md index 8d1147e59b..4d96c6df90 100644 --- a/docs/config_bgp.md +++ b/docs/config_bgp.md @@ -1068,7 +1068,7 @@ Display filtered IPv6 routes for a neighbor in a named VRF: admin@router1.site1# show bgp neighbors vrf vrfA fd00:5::3 filtered-routes ipv6 ``` -When no routes have been filtered, the command returns an empty table. When routes are present, the output format mirrors that of `received-routes` and `advertised-routes`. If the neighbor address is unknown, the VRF does not exist, or the address family is invalid, the PCLI surfaces the underlying vty error string describing the problem. +When no routes have been filtered, the command returns an empty table. When routes are present, the output format mirrors that of `received-routes` and `advertised-routes`. If the neighbor address is unknown, the VRF does not exist, or the address family is invalid, the PCLI surfaces the underlying error string describing the problem. ### REST API diff --git a/docs/sec_security_policy.md b/docs/sec_security_policy.md index f667db0a4e..aad92f9b2c 100644 --- a/docs/sec_security_policy.md +++ b/docs/sec_security_policy.md @@ -131,3 +131,54 @@ Retrieving session information... Attributes: Metadata Security Policy: ``` + +## AES-GCM Encryption + +:::note +AES-GCM encryption is available in SSR version 7.2.0 and above. +::: + +### Overview + +The SSR supports **AES-GCM** (Advanced Encryption Standard – Galois/Counter Mode) as an additional encryption option for session traffic. AES-GCM is an Authenticated Encryption with Associated Data (AEAD) cipher, meaning it provides both **confidentiality** and **integrity** protection in a single cryptographic operation, rather than combining a separate cipher and HMAC as with AES-CBC modes. + +AES-GCM is applied per-packet after SSR session encapsulation. Both SSR metadata and session payload are independently protected, and authentication failures cause the packet to be silently discarded. No changes to routing, session establishment, or service policy behavior are introduced by enabling AES-GCM. + +### Behavior And Compatibility + +| Property | Behavior | +|---|---| +| Confidentiality | Per-packet encryption of SSR metadata and payload. | +| Integrity | Authenticated; authentication failure causes immediate packet discard. | +| HMAC settings | Ignored when AES-GCM is selected — authentication is inherent to GCM. | +| Peer compatibility | If the remote peer does not support AES-GCM, the session falls back to the mutually supported cipher according to existing SSR negotiation behavior. | +| Mixed-version fabrics | Supported, provided peers negotiate a mutually supported cipher. | +| Platform requirement | Requires OpenSSL with GCM capability; supported on existing SSR hardware platforms. | + +### Configuring AES-GCM + +AES-GCM is selected by setting the `encryption-cipher` field of a security policy to the appropriate AES-GCM value. The security policy is then applied in the same locations as any other cipher: + +- `service > security-policy` — payload encryption for sessions +- `network-interface > inter-router-security` — metadata decryption on received SVR traffic +- `network-interface > adjacency > inter-router-security` — metadata encryption for SVR traffic sent to a peer +- `router > inter-node-security` — encryption for HA inter-node communication + +``` +configure authority security + encryption-cipher + encrypt true + hmac-mode disabled +``` + +:::note +Because AES-GCM provides built-in authentication, `hmac-mode` should be set to `disabled`. Any HMAC configuration is ignored at runtime when AES-GCM is the selected cipher. +::: + +:::caution +Changing an encryption cipher is a service-impacting event. Existing sessions cannot be re-keyed in-place. Follow the guidance in [Changing A Security Policy](#changing-a-security-policy) and perform the change during a maintenance window. +::: + +### Verifying AES-GCM Is In Use + +After applying the new policy, use `show sessions by-id` to confirm the cipher is active on new sessions. The **Payload Security Policy** and **Metadata Security Policy** fields identify which security policy is applied per flow. Confirm that the policy you configured with AES-GCM is listed for the expected flows. From 76d864cba6ff351462df5338ec3f2d4760efed33 Mon Sep 17 00:00:00 2001 From: Chris Date: Wed, 13 May 2026 12:03:08 -0400 Subject: [PATCH 3/5] adding pmtu topic for 7.2 --- docs/config_pmtu.mdx | 249 +++++++++++++++++++++++++++++++++++++++++++ sidebars.js | 1 + 2 files changed, 250 insertions(+) create mode 100644 docs/config_pmtu.mdx diff --git a/docs/config_pmtu.mdx b/docs/config_pmtu.mdx new file mode 100644 index 0000000000..6ddade8d6d --- /dev/null +++ b/docs/config_pmtu.mdx @@ -0,0 +1,249 @@ +--- +title: Path MTU Discovery Enhancements +sidebar_label: Path MTU Discovery Enhancements +--- + +#### Version History + +| Release | Modification | +| ------- | ------------ | +| 7.2.0 | Feature introduced | + +## Overview + +The SSR performs Path MTU Discovery (PMTUD) along the overlay to determine the correct maximum transmission unit (MTU) for each peer path. By default, this test runs every ten minutes. If a change in the underlay reduces the available path MTU between two SSRs, the new value is not discovered until the next PMTUD cycle. Additionally, existing sessions continue to use the previous MTU value until the next time those sessions are rebuilt. + +Devices in the underlay may report an ICMP Destination Unreachable / Fragmentation Needed (type 3, code 4) error—referred to here as a _TooBig_ packet—to indicate they could not forward a packet due to an undersized MTU. Prior to SSR 7.2.0, these messages were forwarded to the correct endpoint, but the SSR itself did not act on the MTU value contained in the message, leaving existing sessions with an incorrect PMTU. + +SSR 7.2.0 introduces two complementary enhancements to address these gaps: + +1. **Underlay ICMP reaction** — When the SSR receives a TooBig packet from the underlay, it updates the affected overlay flow and generates a corrected TooBig packet toward the original packet sender, allowing the sender to adjust its segment size. +2. **PMTUD-triggered session refresh** — When a periodic PMTUD cycle discovers a new path MTU, existing sessions that are eligible for flow-move are refreshed to use the new value on the next packet. + +For TCP flows, setting `enforced-mss automatic` on the egress `network-interface` is the recommended complement to these features. It adjusts the TCP MSS advertised at the interface boundary to avoid fragmentation in the first place. See [Configuration](#configuration) for details. + +## How The SSR Reacts to Underlay ICMP TooBig Messages + +The following sequence illustrates what happens when the underlay path MTU changes after a session is already established. + +### Initial State + +```mermaid +sequenceDiagram + participant Client + participant Hub as Hub SSR + participant R1 as Spoke SSR + participant Server + + Client->>Hub: Data (MTU 1500) + Hub->>R1: SVR overlay packet (MTU 1500) + R1->>Server: Data (MTU 1500) + Note over Hub,R1: Underlay MTU = 1500. Session PMTU on both SSRs = 1500. +``` + +The client and server are communicating through two peering SSRs over the overlay. The PMTU is consistent at 1500 across all hops, and both SSRs have applied an MTU of 1500 to the forward flow actions for this session. + +### Underlay MTU Drops — First TooBig Received by Hub + +```mermaid +sequenceDiagram + participant Client + participant Hub as Hub SSR + participant R2 as Underlay Device + participant R1 as Spoke SSR + participant Server + + Note over R2,R1: Underlay MTU between Hub and R2 drops to 1300 + Hub->>R2: SVR packet hub-WAN to spoke-WAN (over 1300 bytes) + R2-->>Hub: ICMP TooBig type 3 code 4, reported MTU = 1300 + Note over Hub: DivertedPacketHandler finds reverse flow. Updates Hub-to-Spoke PMTU to 1300. + Hub-->>Server: New TooBig toward Server + Note over Server: Server adjusts MSS if TCP-capable +``` + +When R2 (an underlay device) cannot forward an oversized packet, it sends a TooBig packet to the Hub's WAN interface. The SSR's `DivertedPacketHandler` processes this message: + +1. It extracts the encapsulated IP header from the TooBig body to identify the affected overlay session. +2. It finds the reverse flow using that header and updates the Hub → Spoke forward flow's PMTU to the value reported by the underlay. +3. It constructs a new TooBig packet directed toward the original packet sender (the Server), so the server's TCP stack can reduce its MSS. + +:::note +The MTU value propagated in the new TooBig packet reflects the underlay-reported value. On paths with encryption, HMAC, FEC, or BFD tunneling overhead, the effective usable MTU will be lower than the raw underlay value. The SSR accounts for these overheads when setting the MSS on forward flow actions. +::: + +## Fabric Fragmentation and Oversize Packet Behavior + +When the PMTU on an overlay (SVR/fabric) path is lower than the MTU of the segment immediately preceding the Hub, packets larger than the PMTU will require fragmentation along the overlay. The SSR always fragments fabric packets when necessary, even when the incoming packet carries the Don't Fragment (DF) bit. This preserves packet delivery but prevents the sender from learning about the smaller path MTU and adjusting its segment size. + +:::note +For TCP traffic, setting `enforced-mss automatic` on the egress `network-interface` is the most reliable way to avoid this scenario. When set, the SSR rewrites the TCP MSS at the interface boundary to match the session MTU (including the path MTU for SVR sessions). This is not the default and must be explicitly configured. +::: + +### Oversize Fabric Packet Behavior + +To allow the sender an opportunity to adjust before fragmenting, you can configure `oversize-fabric-packet-behavior` on either a `network-interface` or a `service-policy`. When enabled, the SSR behavior changes as follows: + +| Setting | Behavior | +| ------- | -------- | +| `false` (default) | Oversized fabric packets are fragmented immediately, matching the current behavior. | +| `true` | The oversized fabric packet is **dropped**, and a TooBig packet is generated toward the sender. This is attempted up to N times per flow. If the sender does not reduce its packet size within those attempts, the SSR falls back to fragmenting. | + +This is a best-effort mechanism. Traffic continues over the overlay (via fragmentation) if the sender does not adjust. + +:::note +Packets that do not carry the DF bit fragment immediately regardless of this setting. Only packets that would otherwise be fragmented on an SVR path are subject to this behavior. +::: + +#### Configuration Location + +`oversize-fabric-packet-behavior` can be configured at two locations, with different trade-offs: + +| Location | Benefit | Consideration | +| -------- | ------- | ------------- | +| `network-interface` | Co-located with `mtu` and `enforced-mss`; applies to all traffic egressing that interface. | Applies to all services on the path, independent of individual service requirements. | +| `service-policy` | Per-service control; different services can have different behaviors. | Applies regardless of which egress interface is selected; a flow-move to a different interface may produce unexpected behavior if the interfaces are not configured consistently. | + +## Configuration + +### Enabling Oversize Fabric Packet Behavior + +#### On a `network-interface` + +``` +config + authority + router + node + device-interface + network-interface + oversize-fabric-packet-behavior true + exit + exit + exit + exit + exit +exit +``` + +#### On a `service-policy` + +``` +config + authority + service-policy + oversize-fabric-packet-behavior true + exit + exit +exit +``` + +### Configuring `enforced-mss` (Recommended for TCP) + +Set `enforced-mss` to `automatic` on egress interfaces to avoid fabric fragmentation for TCP traffic. The SSR calculates the correct MSS from the interface or path MTU for SVR sessions. + +``` +config + authority + router + node + device-interface + network-interface + enforced-mss automatic + exit + exit + exit + exit + exit +exit +``` + +### Configuring PMTUD Interval + +The PMTUD interval (how frequently the SSR probes each overlay path) is configurable at the router level and can be overridden per neighborhood or per adjacency. + +``` +config + authority + router + path-mtu-discovery + enabled true + interval 600 + exit + exit + exit +exit +``` + +| Field | Default | Description | +| ----- | ------- | ----------- | +| `enabled` | `true` | Enables or disables PMTUD for this router. | +| `interval` | `600` | Seconds between PMTUD tests. Valid range: 1–86400. | + +To override the interval for a specific adjacency: + +``` +config + authority + router + node + device-interface + network-interface + adjacency + path-mtu-discovery + enabled true + interval 300 + exit + exit + exit + exit + exit + exit + exit +exit +``` + +### Enabling Session Refresh on PMTU Change + +When a PMTUD cycle discovers a new path MTU, the SSR can automatically refresh existing sessions on that path so they adopt the new MTU value without waiting for a manual rebuild. This requires the affected sessions to be eligible for flow-move, which is controlled by the `session-resiliency` setting in the associated `service-policy`. + +Set `session-resiliency` to either `failover` or `revertible-failover` to enable this behavior: + +``` +config + authority + service-policy + session-resiliency revertible-failover + exit + exit +exit +``` + +When a new PMTU is discovered, the SSR issues a `PathMtuChangeEvent` for the affected path. On the next packet for any eligible session using that path, the SSR diverts the packet to the service area for flow modification, applying the new PMTU. Sessions with `session-resiliency none` are not refreshed and will continue using the previous PMTU value until they are rebuilt by another event. + +--- + +## Verification + +Use `show peers` to confirm the currently discovered path MTU for each peer path: + +```text +admin@node1.router1# show peers +Peer Node Network Interface Destination Status Hostname Path MTU +------------------------ --------- ------------------- --------------- -------- ------------ ---------- +router2 node1 wan0 192.0.2.10 Up router2.lab 1300 +``` + +A `Path MTU` value of `0` indicates PMTUD is disabled or has not yet completed a test cycle. + +## Troubleshooting + +- If the path MTU shown by `show peers` does not reflect the expected value, verify that `path-mtu-discovery > enabled` is `true` on both sides of the adjacency. +- If TCP sessions continue to fragment after configuring `enforced-mss automatic`, confirm the setting is applied to the correct egress interface and that both peers have completed a PMTUD cycle. +- If existing sessions are not picking up a new PMTU after a PMTUD cycle, verify the `service-policy` for those sessions has `session-resiliency` set to `failover` or `revertible-failover`. + +## Related Topics + +- [Concepts: Machine to Machine Communication](concepts_machine_communication.md) — path MTU discovery protocol details and BFD traffic patterns. +- [Configuration Reference Guide](config_reference_guide.md) — full parameter reference for `path-mtu-discovery`, `enforced-mss`, and `session-resiliency`. +- [Configuring Session Recovery Detection](config_session_recovery.md) — session health-check and flow rebuild mechanisms. +- [Configuring Forward Error Correction](config_forward_error_correction.md) — complementary resiliency feature for packet loss. diff --git a/sidebars.js b/sidebars.js index 2448b5b239..44cd4cf22e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -283,6 +283,7 @@ module.exports = { "config_prefix_delegation", "config_session_recovery", "config_forward_error_correction", + "config_pmtu", "config_management_over_forwarding", "config_domain-based_web_filter", "config_EthoSVR", From 94e4ffcf506ec8cd4e1ec3f00e75118c1d93df63 Mon Sep 17 00:00:00 2001 From: Chris Date: Wed, 13 May 2026 16:34:05 -0400 Subject: [PATCH 4/5] most of TJ's comments. Need the graphics to display so I can verify whether changes are needed, and need to get stats example. --- docs/config_pmtu.mdx | 60 ++++++++------------------------------------ 1 file changed, 10 insertions(+), 50 deletions(-) diff --git a/docs/config_pmtu.mdx b/docs/config_pmtu.mdx index 6ddade8d6d..6f3b6637b6 100644 --- a/docs/config_pmtu.mdx +++ b/docs/config_pmtu.mdx @@ -13,12 +13,13 @@ sidebar_label: Path MTU Discovery Enhancements The SSR performs Path MTU Discovery (PMTUD) along the overlay to determine the correct maximum transmission unit (MTU) for each peer path. By default, this test runs every ten minutes. If a change in the underlay reduces the available path MTU between two SSRs, the new value is not discovered until the next PMTUD cycle. Additionally, existing sessions continue to use the previous MTU value until the next time those sessions are rebuilt. -Devices in the underlay may report an ICMP Destination Unreachable / Fragmentation Needed (type 3, code 4) error—referred to here as a _TooBig_ packet—to indicate they could not forward a packet due to an undersized MTU. Prior to SSR 7.2.0, these messages were forwarded to the correct endpoint, but the SSR itself did not act on the MTU value contained in the message, leaving existing sessions with an incorrect PMTU. +Devices in the underlay may report an ICMP Destination Unreachable / Fragmentation Needed (type 3, code 4) error, referred to here as a _TooBig_ packet, to indicate they could not forward a packet due to an undersized MTU. Prior to SSR 7.2.0, these messages were forwarded to the correct endpoint, but the SSR itself did not act on the MTU value contained in the message, leaving existing sessions with an incorrect PMTU. SSR 7.2.0 introduces two complementary enhancements to address these gaps: 1. **Underlay ICMP reaction** — When the SSR receives a TooBig packet from the underlay, it updates the affected overlay flow and generates a corrected TooBig packet toward the original packet sender, allowing the sender to adjust its segment size. -2. **PMTUD-triggered session refresh** — When a periodic PMTUD cycle discovers a new path MTU, existing sessions that are eligible for flow-move are refreshed to use the new value on the next packet. + +2. **Session Refresh** - The flow which was traversed to trigger the TooBig response from the underlay is now updated to use the MTU reported in the TooBig packet. For TCP flows, setting `enforced-mss automatic` on the egress `network-interface` is the recommended complement to these features. It adjusts the TCP MSS advertised at the interface boundary to avoid fragmentation in the first place. See [Configuration](#configuration) for details. @@ -61,14 +62,14 @@ sequenceDiagram Note over Server: Server adjusts MSS if TCP-capable ``` -When R2 (an underlay device) cannot forward an oversized packet, it sends a TooBig packet to the Hub's WAN interface. The SSR's `DivertedPacketHandler` processes this message: +When R2 (an underlay device) cannot forward an oversized packet, it sends a TooBig packet to the Hub's WAN interface. The SSR processes this message and does the following: 1. It extracts the encapsulated IP header from the TooBig body to identify the affected overlay session. 2. It finds the reverse flow using that header and updates the Hub → Spoke forward flow's PMTU to the value reported by the underlay. 3. It constructs a new TooBig packet directed toward the original packet sender (the Server), so the server's TCP stack can reduce its MSS. :::note -The MTU value propagated in the new TooBig packet reflects the underlay-reported value. On paths with encryption, HMAC, FEC, or BFD tunneling overhead, the effective usable MTU will be lower than the raw underlay value. The SSR accounts for these overheads when setting the MSS on forward flow actions. +The MTU value propagated in the new TooBig packet reflects the underlay-reported value. On paths with encryption, HMAC, FEC, or BFD tunneling overhead, the effective usable MTU will be lower than the raw underlay value. The SSR accounts for these overheads when setting the MTU on forward flow actions. ::: ## Fabric Fragmentation and Oversize Packet Behavior @@ -76,33 +77,9 @@ The MTU value propagated in the new TooBig packet reflects the underlay-reported When the PMTU on an overlay (SVR/fabric) path is lower than the MTU of the segment immediately preceding the Hub, packets larger than the PMTU will require fragmentation along the overlay. The SSR always fragments fabric packets when necessary, even when the incoming packet carries the Don't Fragment (DF) bit. This preserves packet delivery but prevents the sender from learning about the smaller path MTU and adjusting its segment size. :::note -For TCP traffic, setting `enforced-mss automatic` on the egress `network-interface` is the most reliable way to avoid this scenario. When set, the SSR rewrites the TCP MSS at the interface boundary to match the session MTU (including the path MTU for SVR sessions). This is not the default and must be explicitly configured. -::: - -### Oversize Fabric Packet Behavior - -To allow the sender an opportunity to adjust before fragmenting, you can configure `oversize-fabric-packet-behavior` on either a `network-interface` or a `service-policy`. When enabled, the SSR behavior changes as follows: - -| Setting | Behavior | -| ------- | -------- | -| `false` (default) | Oversized fabric packets are fragmented immediately, matching the current behavior. | -| `true` | The oversized fabric packet is **dropped**, and a TooBig packet is generated toward the sender. This is attempted up to N times per flow. If the sender does not reduce its packet size within those attempts, the SSR falls back to fragmenting. | - -This is a best-effort mechanism. Traffic continues over the overlay (via fragmentation) if the sender does not adjust. - -:::note -Packets that do not carry the DF bit fragment immediately regardless of this setting. Only packets that would otherwise be fragmented on an SVR path are subject to this behavior. +For TCP traffic, setting `enforced-mss automatic` on the egress `network-interface` is the most reliable way to avoid this scenario. When set, the SSR rewrites the TCP MSS at the interface boundary to match the session MTU (including the path MTU for SVR sessions). This is commonly known as `MSS Clamping` and is not the default; it must be explicitly configured. ::: -#### Configuration Location - -`oversize-fabric-packet-behavior` can be configured at two locations, with different trade-offs: - -| Location | Benefit | Consideration | -| -------- | ------- | ------------- | -| `network-interface` | Co-located with `mtu` and `enforced-mss`; applies to all traffic egressing that interface. | Applies to all services on the path, independent of individual service requirements. | -| `service-policy` | Per-service control; different services can have different behaviors. | Applies regardless of which egress interface is selected; a flow-move to a different interface may produce unexpected behavior if the interfaces are not configured consistently. | - ## Configuration ### Enabling Oversize Fabric Packet Behavior @@ -202,26 +179,6 @@ config exit ``` -### Enabling Session Refresh on PMTU Change - -When a PMTUD cycle discovers a new path MTU, the SSR can automatically refresh existing sessions on that path so they adopt the new MTU value without waiting for a manual rebuild. This requires the affected sessions to be eligible for flow-move, which is controlled by the `session-resiliency` setting in the associated `service-policy`. - -Set `session-resiliency` to either `failover` or `revertible-failover` to enable this behavior: - -``` -config - authority - service-policy - session-resiliency revertible-failover - exit - exit -exit -``` - -When a new PMTU is discovered, the SSR issues a `PathMtuChangeEvent` for the affected path. On the next packet for any eligible session using that path, the SSR diverts the packet to the service area for flow modification, applying the new PMTU. Sessions with `session-resiliency none` are not refreshed and will continue using the previous PMTU value until they are rebuilt by another event. - ---- - ## Verification Use `show peers` to confirm the currently discovered path MTU for each peer path: @@ -235,11 +192,14 @@ router2 node1 wan0 192.0.2.10 Up A `Path MTU` value of `0` indicates PMTUD is disabled or has not yet completed a test cycle. +A new stat, `stats/icmp/flow-mtu-updates`, provides a count of flows that have had their MTU updated at runtime via a TooBig packet. This counter is reset when the system resets (not persisted). + +**need stat example + ## Troubleshooting - If the path MTU shown by `show peers` does not reflect the expected value, verify that `path-mtu-discovery > enabled` is `true` on both sides of the adjacency. - If TCP sessions continue to fragment after configuring `enforced-mss automatic`, confirm the setting is applied to the correct egress interface and that both peers have completed a PMTUD cycle. -- If existing sessions are not picking up a new PMTU after a PMTUD cycle, verify the `service-policy` for those sessions has `session-resiliency` set to `failover` or `revertible-failover`. ## Related Topics From bf3af36016ab2c215e4d812ff46dcd83f2272b7f Mon Sep 17 00:00:00 2001 From: Chris Date: Thu, 14 May 2026 10:35:05 -0400 Subject: [PATCH 5/5] Updates per Dennis' comments --- docs/sec_security_policy.md | 96 +++++++++++++++++++++++++++++++++++-- 1 file changed, 93 insertions(+), 3 deletions(-) diff --git a/docs/sec_security_policy.md b/docs/sec_security_policy.md index aad92f9b2c..a726c8f1b2 100644 --- a/docs/sec_security_policy.md +++ b/docs/sec_security_policy.md @@ -157,7 +157,7 @@ AES-GCM is applied per-packet after SSR session encapsulation. Both SSR metadata ### Configuring AES-GCM -AES-GCM is selected by setting the `encryption-cipher` field of a security policy to the appropriate AES-GCM value. The security policy is then applied in the same locations as any other cipher: +AES-GCM is selected by setting the `encryption-cipher` field of a security policy to the appropriate AES-GCM value, either `aes-gcm-128` or `aes-gcm-256`. The security policy is then applied in the same locations as any other cipher: - `service > security-policy` — payload encryption for sessions - `network-interface > inter-router-security` — metadata decryption on received SVR traffic @@ -166,7 +166,7 @@ AES-GCM is selected by setting the `encryption-cipher` field of a security polic ``` configure authority security - encryption-cipher + encryption-cipher aes-gcm-256 encrypt true hmac-mode disabled ``` @@ -181,4 +181,94 @@ Changing an encryption cipher is a service-impacting event. Existing sessions ca ### Verifying AES-GCM Is In Use -After applying the new policy, use `show sessions by-id` to confirm the cipher is active on new sessions. The **Payload Security Policy** and **Metadata Security Policy** fields identify which security policy is applied per flow. Confirm that the policy you configured with AES-GCM is listed for the expected flows. +After applying the new policy, use `show sessions by-id` to confirm the cipher is active on new sessions. The **Payload Security Policy** and **Metadata Security Policy** fields identify which security policy is applied per flow. The **Action List** fields include the GCM encryption and `decryption actions: `AesGcmEncrypt`, `AesGcmDecrypt`, `AesGcmEncryptSvr2`, and `AesGcmDecryptSvr2. Confirm that the policy you configured with AES-GCM is listed for the expected flows. + +``` +admin@test1.combo1# sho sessions by-id 37ed5241-d5d5-4120-b168-884c619935a4 +Thu 2026-05-14 12:00:14 UTC +Retrieving session information... + +============================================================================================================================================================================ + combo1.test1 Session ID: 37ed5241-d5d5-4120-b168-884c619935a4 +============================================================================================================================================================================ + Service Name: east + Service Route Name: + Session Source: SourceType: INTER_ROUTER + Session Type: HTTPS + Service Class: Standard + Source Tenant: red + Destination Peer Name: N/A + Source Peer Name: combo2 + Inter Node: N/A + Inter Router: N/A + Ingress Source Nat: N/A + Payload Security Policy: aes1 + Payload Encrypted: True + Common Name Info: N/A + Tcp Time To Establish: N/A + Tls Time To Establish: N/A + Domain Name: N/A + Uri: N/A + Category: N/A + Override Service Name: N/A + App Stats Tracking Key: N/A + Session Keys: + Forward Session Key: [discriminator 4294967297, tenant red, peer combo2, src ip 172.16.2.201, dest ip 172.16.1.201, src port 443, dest port 10000, proto 17] + Reverse Session Key: [discriminator 4294967297, tenant red, peer combo2, src ip 172.16.1.201, dest ip 172.16.2.201, src port 10000, dest port 443, proto 17] + State Info: + Session State: ESTABLISHED + Redundancy State: SYNCED + Time Info: + Start Time: 0 days 0:00:12 + Ttl Duration For Database: 1900 + Forward Flows: + Key: [src ip 172.16.3.2, dest ip 172.16.3.1, src port 16384, dest port 16385, proto 17, interface 2.0] + Direction: forward + Tcp State: N/A + Packets Received: 999 + Packets Sent: 999 + Bytes Received: 152563 + Bytes Sent: 123876 + Tcp Retransmission Count: N/A + Decrypt Security Policy: interfabric + Action List: Ingress AesGcmDecryptMetadata ForwardMetadataRemove AesGcmDecrypt TtlValidateIpv4 IpHeaderTransform EthernetHeaderTransform AppForward + Time To Live: 1897 + Path Index: 5 + Attributes: + Path Key: NextHop : 1-1.0=172.16.1.201, destination Ip 172.16.1.0/24 + Arp Status: Valid + Waypoint Key: + Source Nat Key: + Metadata Security Policy: + Reverse Flows: + Key: [src ip 172.16.1.201, dest ip 172.16.2.201, src port 10000, dest port 443, proto 17, interface 1.0] + Direction: reverse + Tcp State: N/A + Packets Received: 995 + Packets Sent: 995 + Bytes Received: 123380 + Bytes Sent: 151464 + Tcp Retransmission Count: N/A + Decrypt Security Policy: + Action List: Ingress TtlValidateIpv4 IpHeaderTransform AesGcmEncrypt AppMetadataAdd AesGcmEncryptMetadata EthernetHeaderTransform AppForward + Time To Live: 1897 + Path Index: 5 + Attributes: + Path Key: NextHop : 1-2.0=172.16.3.2, destination Ip 172.16.3.2/32 + Arp Status: Valid + Waypoint Key: + Source Nat Key: + Metadata Security Policy: interfabric + App Identification: + Application: east + Domain Name: N/A + Uri: N/A + Category: N/A + Subcategory: N/A + Override Service Name: N/A + App Stats Tracking Key: N/A + +Completed in 0.07 seconds +``` + +