From 791282079d1c2ec0af8fa12ed40932ff1e225f2f Mon Sep 17 00:00:00 2001 From: Chris Date: Mon, 11 May 2026 16:18:09 -0400 Subject: [PATCH 01/16] 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 02/16] 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 03/16] 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 04/16] 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 05/16] 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 +``` + + From c5f3aaf8d05701ed3eaa5b7b407f520b42f20936 Mon Sep 17 00:00:00 2001 From: Chris Date: Fri, 15 May 2026 09:37:25 -0400 Subject: [PATCH 06/16] interim commit --- docs/concepts_machine_communication.md | 4 +++- docs/config_pmtu.mdx | 12 ++---------- 2 files changed, 5 insertions(+), 11 deletions(-) diff --git a/docs/concepts_machine_communication.md b/docs/concepts_machine_communication.md index c6c027b9b7..9b8196419c 100644 --- a/docs/concepts_machine_communication.md +++ b/docs/concepts_machine_communication.md @@ -87,7 +87,9 @@ Peering SSR routers will perform path MTU discovery on each peer path between ea In order to accommodate these deployments where “ICMP Destination Unreachable - Fragmentation Needed” response messages are not generated (RFC1911 is not followed), three successive non-responses are considered equivalent to ICMP responses for the purposes of driving the algorithm with an inferred MTU. -The discovered MTU is viewable in the output of `show peers`. +The discovered MTU is viewable in the output of `show peers`. + +For additional information, see [Path MTU Discovery](config_pmtu.mdx). ### Secure Vector Routing Traffic diff --git a/docs/config_pmtu.mdx b/docs/config_pmtu.mdx index 6f3b6637b6..e05dc112e8 100644 --- a/docs/config_pmtu.mdx +++ b/docs/config_pmtu.mdx @@ -1,16 +1,8 @@ --- -title: Path MTU Discovery Enhancements -sidebar_label: Path MTU Discovery Enhancements +title: Path MTU Discovery +sidebar_label: Path MTU Discovery --- -#### 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. From da3441a6fc8720320b893500a6558c59a20e8041 Mon Sep 17 00:00:00 2001 From: Mike Adams Date: Fri, 15 May 2026 10:33:42 -0400 Subject: [PATCH 07/16] docs: add SAN URI peering identity support for SSR 7.2.0 - Add subject_alt_names parameter to CSR API documentation - Document urn:ssr:peering SAN URI for SVRv2 peer identity - Highlight HA use case: unique CNs per node with shared SAN URI - Update peer authentication flow: CN check then SAN URI fallback - Replace custom_ssr_peering with my_peering_cert in examples - Add legacy note for custom_ssr_peering disk-based fallback - Add 5 new audit event types (generate/delete private key, update/delete certificate, delete CSR) - Update generate_csr audit event with subject_alt_names field - Remove role parameter references (removed in PR #20519) Refs: ssr#20819, ssr#20767, ssr#20519 --- docs/cert_validation_requirements.md | 2 + docs/config_custom_certs.md | 53 +++++++++++------ docs/sec-cert-based-encrypt.md | 85 +++++++++++++++++++++++++--- docs/sec_enhanced_key_mgmt.md | 71 +++++++++++++++++++---- 4 files changed, 175 insertions(+), 36 deletions(-) diff --git a/docs/cert_validation_requirements.md b/docs/cert_validation_requirements.md index 6011391be0..ee0a337e0e 100644 --- a/docs/cert_validation_requirements.md +++ b/docs/cert_validation_requirements.md @@ -8,6 +8,7 @@ sidebar_label: Certificate Requirements and Validation | Release | Modification | | ------- | --------------------------- | | 7.0.0 | Certificate management and validation support added. | +| 7.2.0 | Subject Alternative Name URI support for peering identity. | This page describes the certificate properties that the SSR enforces, how `validation-mode` affects behavior, and the differences between config-time and runtime validation. @@ -112,6 +113,7 @@ Client certificates used for peering are validated as leaf (end-entity) certific | --- | --- | | Signature Algorithm | Must be an [accepted algorithm](#accepted-cryptographic-algorithms). | | Public Key | Must be an [accepted key type and size](#key-requirements). | +| Subject Alternative Name (optional) | Starting in SSR 7.2.0, a `urn:ssr:peering:` SAN URI can be used to carry SVRv2 peering identity as an alternative to the Common Name. See [Enhanced Security Key Management — API Naming Rules](sec_enhanced_key_mgmt.md#api-naming-rules) for details. | ### Intermediate CA Certificates diff --git a/docs/config_custom_certs.md b/docs/config_custom_certs.md index 3d5ca718b6..f69e2a024f 100644 --- a/docs/config_custom_certs.md +++ b/docs/config_custom_certs.md @@ -7,7 +7,8 @@ sidebar_label: Configure Certificate Management | Release | Modification | | ------- | --------------------------- | -| 7.0.0 | Certificate Management support added. | +| 7.0.0 | Certificate Management support added. | +| 7.2.0 | Subject Alternative Name support added to CSR generation. | Security is a critical component of SD-WAN products. The effectiveness of any security strategy relies on the strength of the security algorithm and how related information is exchanged between participants. @@ -51,8 +52,8 @@ The following are some details of certificate security. ## Provisioning Process -:::important -It is necessary for all of the REST APIs to use the name `custom_ssr_peering` in order for this private key and certificate to be visible and usable by Enhanced Security Key Management in 7.0. This is a reserved name specifically used by the Enhanced Security Key Management feature. +:::note Legacy Name +In SSR 7.0.x, the `name` field in all REST API calls was required to be `custom_ssr_peering` (a reserved name) for ESKM visibility. Starting with SSR 7.1.0, any consistent name may be used. The examples below use `my_peering_cert`. ::: :::tip Swagger API Reference @@ -191,7 +192,7 @@ Create the following file (update algorithm and key size to your preference): ``` { - "name": "custom_ssr_peering", + "name": "my_peering_cert", "algorithm": "RSA", "rsa_key_size": "2048" } @@ -213,7 +214,7 @@ curl -k -X POST https://10.27.35.89/api/v1/router/combo-east/node/node2/private- -d @key_request.json ``` -Upon success, `ssh` to the target SSR and verify that `/etc/128technology/pki/custom_ssr_peering.key` exists on disk. +Upon success, `ssh` to the target SSR and verify that `/etc/128technology/pki/my_peering_cert.key` exists on disk. ### Issue a `certificate-signing-request` @@ -226,11 +227,13 @@ This requirement is lifted starting with SSR 7.1.0. ::: -1. Create a file containing the CSR request body. At a minimum provide `name` and a `common_name` that is unique to this router or node: +1. Create a file containing the CSR request body. At a minimum provide `name` and a `common_name`: :::important Naming Rules -- **`name`** must be **the same value across all routers and nodes** — `custom_ssr_peering` in SSR 7.0.x (reserved). This is the authority-wide identifier required for ESKM visibility. -- **`common_name`** must be **unique per router/node** and must **exactly match** that router's configured `peering-common-name`. Using the wrong `common_name` will cause ESKM peer authentication to fail. +- **`name`** must be **the same value across all routers and nodes**. In SSR 7.1+, any consistent name may be used. +- **`common_name`** must be **unique per router/node**. It must match that router's configured `peering-common-name` — either directly, or via a `urn:ssr:peering` SAN URI in the certificate (SSR 7.2.0+). + +For full details on SAN URI peering identity, see [Enhanced Security Key Management — API Naming Rules](sec_enhanced_key_mgmt.md#api-naming-rules). Example mapping for a two-router deployment: @@ -240,15 +243,27 @@ Example mapping for a two-router deployment: | combo-west | `west-alias` | `west-alias` | ::: -**csr_request.json** +**csr_request.json** (minimum): ``` { - "name": "custom_ssr_peering", + "name": "my_peering_cert", "common_name": "east-alias" } ``` +**csr_request.json** (with Subject Alternative Name URI for HA): + +```json +{ + "name": "my_peering_cert", + "common_name": "combo-east-node1", + "subject_alt_names": [ + {"type": "urn_ssr_peering", "value": "east-alias"} + ] +} +``` + This example represents the minimum requirements. Any of the following additional details may be added to the request: - country_name (string, optional): The country name. @@ -261,6 +276,12 @@ This example represents the minimum requirements. Any of the following additiona - rsa_key_size (integer, optional): The RSA key size. Only valid when algorithm is set to “RSA”. Valid key sizes are any multiple of 256 between 2048 and 4096. - ecc_curve (string, optional): The ECC curve to use. Only valid when algorithm is set to “ECC”.Valid curves are: (SECP256R, SECP384R1, SECP521R1) - validity_period (integer, optional): The validity period in days. +- subject_alt_names (array, optional, SSR 7.2.0+): An array of Subject Alternative Name entries to include in the CSR. Each entry is an object with `type` and `value` fields. Supported types: + - `dns` — a DNS hostname (e.g., `"example.com"`) + - `ip` — an IPv4 or IPv6 address (e.g., `"192.168.1.1"`) + - `email` — an email address (e.g., `"admin@example.com"`) + - `uri` — a URI (e.g., `"https://example.com"`) + - `urn_ssr_peering` — a convenience alias that automatically expands the value to `URI:urn:ssr:peering:`. Use this type to carry the SVRv2 peering identity in the SAN extension. 2. Issue the CSR request to the SSR: @@ -301,7 +322,7 @@ When the signed certificate is returned, instruct the SSR to ingest the certific ``` POST /api/v1/router/{router_name}/node/{node_name}/certificate { - "name": "custom_ssr_peering", + "name": "my_peering_cert", "certificate": "-----BEGIN CERTIFICATE----- MIIF3DCCBESgAwIBAgIKAf9HQjJKSQd1lTANBgkqhkiG9w0BAQsFADBaMQswCQYD VQQGEwJERTERMA8GA1UECgwIT3BlblhQS0kxDDAKBgNVBAsMA1BLSTEqMCgGA1UE @@ -319,8 +340,8 @@ Once the certificate is successfully ingested, verify that the certificate was a 1. `ssh` to the SSR. 2. Log in as the root user: `sudo su`. -3. Verify that `/etc/128technology/pki/custom_ssr_peering.pem` exists on disk. - `ls -l /etc/128technology/pki/custom_ssr_peering.pem` +3. Verify that `/etc/128technology/pki/my_peering_cert.pem` exists on disk. + `ls -l /etc/128technology/pki/my_peering_cert.pem` ### Activate the Certificate in Configuration @@ -330,9 +351,9 @@ On the Conductor, configure `client-certificate` using the same `name` value use ``` config authority - client-certificate custom_ssr_peering - name custom_ssr_peering - file custom_ssr_peering + client-certificate my_peering_cert + name my_peering_cert + file my_peering_cert validation-mode strict exit exit diff --git a/docs/sec-cert-based-encrypt.md b/docs/sec-cert-based-encrypt.md index c99ac496e1..13fc7c21a9 100644 --- a/docs/sec-cert-based-encrypt.md +++ b/docs/sec-cert-based-encrypt.md @@ -6,7 +6,8 @@ sidebar_label: Certificate-based Security Encryption | Release | Modification | | ------- | --------------------------- | -| 7.1.0 | Certificate-based Security Encryption support added. | +| 7.1.0 | Certificate-based Security Encryption support added. | +| 7.2.0 | Subject Alternative Name support added to CSR generation. New audit events for certificate lifecycle. | In addition to Enhanced Security Key Management, the SSR offers certificate based security encryption to encrypt, validate, and exchange certificates between devices within the network. @@ -191,7 +192,7 @@ Create the following file (updated to the customers algorithm/key size preferenc ``` { - "name": "custom_ssr_peering", + "name": "my_peering_cert", "algorithm": "RSA", "rsa_key_size": "2048" } @@ -206,19 +207,19 @@ curl -k -X POST https://10.27.35.89/api/v1/private-key -d @key_request.json ``` -Upon success, you can verify that the key was created by logging on to the SSR, `ssh` into a linux shell, and ensuring that `/etc/128technology/pki/custom_ssr_peering.key` exists on disk. +Upon success, you can verify that the key was created by logging on to the SSR, `ssh` into a linux shell, and ensuring that `/etc/128technology/pki/my_peering_cert.key` exists on disk. ### Issue a `certificate-signing-request` In order to create a signed certificate by the CA for the SSR, the CA needs a `certificate-signing-request`. Instruct the SSR to create the request using the values provided; at a minimum the `name` and `common-name`. The SSR must sign the request with its private-key. -1. Create a file that contains the body of the CSR-request. At a minimum this must include the name `custom_ssr_peering`, and the common name: +1. Create a file that contains the body of the CSR-request. At a minimum this must include the `name` and the `common_name`: **csr_request.json** ``` { - "name": "custom_ssr_peering", + "name": "my_peering_cert", "common_name": "SSR_12345679" } ``` @@ -235,6 +236,7 @@ This example represents the minimum requirements. Any of the following additiona - rsa_key_size (integer, optional): The RSA key size. Only valid when algorithm is set to “RSA”. Valid key sizes are any multiple of 256 between 2048 and 4096. - ecc_curve (string, optional): The ECC curve to use. Only valid when algorithm is set to “ECC”.Valid curves are: (SECP256R, SECP384R1, SECP521R1) - validity_period (integer, optional): The validity period in days. +- subject_alt_names (array, optional, SSR 7.2.0+): An array of Subject Alternative Name entries to include in the CSR. Each entry is an object with `type` and `value` fields. Supported types: `dns`, `ip`, `email`, `uri`, `urn_ssr_peering`. For details, see [Configure Certificate Management](config_custom_certs.md#issue-a-certificate-signing-request). 2. Issue the CSR request to the SSR: @@ -270,7 +272,7 @@ When the signed certificate is returned, instruct the SSR to ingest the certific ``` { - "name": "custom_ssr_peering", + "name": "my_peering_cert", "certificate": "-----BEGIN CERTIFICATE----- MIIF3DCCBESgAwIBAgIKAf9HQjJKSQd1lTANBgkqhkiG9w0BAQsFADBaMQswCQYD VQQGEwJERTERMA8GA1UECgwIT3BlblhQS0kxDDAKBgNVBAsMA1BLSTEqMCgGA1UE @@ -288,8 +290,8 @@ Once the certificate is successfully ingested, verify that the certificate was a 1. `ssh` to the SSR. 2. Log in as the root user: `sudo su`. -3. Verify that `/etc/128technology/pki/custom_ssr_peering.pem` exists on disk. - `ls -l /etc/128technology/pki/custom_ssr_peering.pem` +3. Verify that `/etc/128technology/pki/my_peering_cert.pem` exists on disk. + `ls -l /etc/128technology/pki/my_peering_cert.pem` ### Configure the Certificate @@ -371,7 +373,20 @@ Audit events and logs are generated for the following events: Node: test-1 Description: Generated CSR for: TestCertificate Json Event Detail: {"name":"TestCertificate","common_name":"example.com","country_name":"US","state_province_name":"California","locality_name":"San - Francisco","organization_name":"ExampleOrg","organizational_unit_name":"IT","email_address":"admin@example.com","validity_period_days":365} + Francisco","organization_name":"ExampleOrg","organizational_unit_name":"IT","email_address":"admin@example.com","validity_period_days":365,"subject_alt_names":[]} + Permitted: True +``` + +- Generate Private Key + +``` +======================================================================================================================================================= + 2025-03-19T20:50:35.173Z Generated private key. +======================================================================================================================================================= + Type: system.generate_private_key + Node: test-1 + Description: Generated private key for: TestCertificate + Json Event Detail: {"name":"TestCertificate","algorithm":"RSA","rsa_key_size":2048} Permitted: True ``` @@ -400,3 +415,55 @@ Audit events and logs are generated for the following events: GMT","crl_url":"http://10.27.39.143/testCrl.pem","size":14162,"total_entries":279,"added_entries":0,"removed_entries":0,"success":true,"certificate_authority":"/C=US/O=Google Trust Services/CN=WR2"} Permitted: True ``` + +- Update Certificate + +``` +======================================================================================================================================================= + 2025-03-26T21:22:43.108Z Updated a certificate. +======================================================================================================================================================= + Type: system.update_certificate + Node: test-1 + Description: Updated certificate: TestCertificate + Json Event Detail: {"purpose":"TLS Web Client Authentication","common_name":"example.com","crl_urls":[],"certificate_authority":"N/A","fingerprint":"6D:C7:8E:48:4F:55:63:D9:AB:70:66:CD:29:4E:1C:37:CF:89:17:B0"} + Permitted: True +``` + +- Delete Certificate + +``` +======================================================================================================================================================= + 2025-03-26T21:22:43.108Z Deleted a certificate. +======================================================================================================================================================= + Type: system.delete_certificate + Node: test-1 + Description: Deleted certificate: TestCertificate + Json Event Detail: {"name":"TestCertificate"} + Permitted: True +``` + +- Delete Private Key + +``` +======================================================================================================================================================= + 2025-03-26T21:22:43.108Z Deleted a private key. +======================================================================================================================================================= + Type: system.delete_private_key + Node: test-1 + Description: Deleted private key: TestCertificate + Json Event Detail: {"name":"TestCertificate"} + Permitted: True +``` + +- Delete CSR + +``` +======================================================================================================================================================= + 2025-03-26T21:22:43.108Z Deleted a certificate signing request. +======================================================================================================================================================= + Type: system.delete_csr + Node: test-1 + Description: Deleted CSR: TestCertificate + Json Event Detail: {"name":"TestCertificate"} + Permitted: True +``` diff --git a/docs/sec_enhanced_key_mgmt.md b/docs/sec_enhanced_key_mgmt.md index 8b6fa23a69..5eb1becc04 100644 --- a/docs/sec_enhanced_key_mgmt.md +++ b/docs/sec_enhanced_key_mgmt.md @@ -9,6 +9,7 @@ sidebars-label: Enhanced Security Key Management | ------- | --------------------------- | | 7.0.1 | Enhanced Security Key Management support added. | | 7.1.3 | Support for ML-KEM added. | +| 7.2.0 | Subject Alternative Name (SAN) URI support for peering identity. | Security is a critical component of [SD-WAN (software-defined wide area network)](https://www.juniper.net/us/en/products/routers/session-smart-router.html) products in today’s market. [The SSR (Session Smart Router)](about_128t.md) offers several means of ensuring the integrity of data transmitted through the router, such as encrypting application payload content, encrypting SVR (Secure Vector Routing) metadata, and authentication for metadata. @@ -69,7 +70,7 @@ When using CA-signed certificates, the end-to-end provisioning sequence must be 1. Authenticate to the Conductor REST API (`POST /api/v1/login`) and store the bearer token. 2. Generate a private key on the target router's node (`POST /api/v1/router//node//private-key`) — the key never leaves the SSR. -3. Generate a CSR on the same target (`GET /api/v1/router//node//certificate-request`) using a `common_name` that matches that router's `peering-common-name`. +3. Generate a CSR on the same target (`GET /api/v1/router//node//certificate-request`) using a `common_name` that matches that router's `peering-common-name`, or alternatively, using any unique `common_name` with a `urn:ssr:peering` SAN URI that matches the `peering-common-name`. See [API Naming Rules](#api-naming-rules) for details. 4. Submit the CSR to your Certificate Authority and obtain a signed certificate. 5. Ingest the signed certificate back into the SSR (`POST /api/v1/router//node//certificate`). 6. **Activate the certificate in configuration** — having the file on disk is not sufficient. Configure `authority client-certificate` with a `name` and `file` matching the API artifact name. See [Activating the Certificate in Configuration](#activating-the-certificate-in-configuration). @@ -84,16 +85,54 @@ Consistent naming across all API calls and configuration is critical: | Field | Scope | Rule | |---|---|---| -| `name` (in all API requests) | Authority-wide | **Must be identical across all routers and nodes.** Use `custom_ssr_peering` in SSR 7.0.x (reserved name). In SSR 7.1+, any consistent name may be used. | -| `common_name` (in CSR request) | Per-router / per-node | **Must be unique per router or HA node**, and must **exactly match** that router's configured `peering-common-name`. | -| `peering-common-name` (in config) | Per-router | Unique alias per router. Must match the `common_name` used in that router's CSR. | +| `name` (in all API requests) | Authority-wide | **Must be identical across all routers and nodes.** In SSR 7.1+, any consistent name may be used. | +| `common_name` (in CSR request) | Per-router / per-node | **Must be unique per router or HA node.** Must match the router's configured `peering-common-name` — either directly in the `common_name` field, or via a `urn:ssr:peering` SAN URI (see below). | +| `peering-common-name` (in config) | Per-router | Unique alias per router. Must match either the `common_name` or a `urn:ssr:peering` SAN URI in that router's certificate. | -**Example mapping for a two-router deployment:** +:::note Legacy Name +In SSR 7.0.x, the `name` field was required to be `custom_ssr_peering` (a reserved name). This is no longer required in SSR 7.1+. If no certificate is configured, the SSR will fall back to searching for certificates named `custom_ssr_peering` on disk for backward compatibility. +::: + +##### Peering Identity via Subject Alternative Name URI (SSR 7.2.0+) + +Starting in SSR 7.2.0, the peering identity can be carried in a Subject Alternative Name (SAN) URI extension instead of the Common Name (CN). This is especially useful in **HA deployments**, where both nodes in a router share the same `peering-common-name` but enterprise PKI policies require unique CNs per certificate. + +When verifying a peer's identity, the SSR checks the certificate CN first. If the CN does not match the configured `peering-common-name`, the SSR falls back to checking for a SAN URI of the form: + +``` +urn:ssr:peering: +``` + +If a matching SAN URI is found, the certificate is accepted. This allows each HA node to have a unique CN while sharing the same peering identity through the SAN URI. -| Router | `peering-common-name` in config | `common_name` in CSR | `name` in all API requests | -|---|---|---|---| -| combo-east | `east-alias` | `east-alias` | `custom_ssr_peering` | -| combo-west | `west-alias` | `west-alias` | `custom_ssr_peering` | +To include a SAN URI in a CSR, add a `subject_alt_names` array to the CSR request body using the `urn_ssr_peering` convenience type: + +```json +{ + "name": "my_peering_cert", + "common_name": "combo-east-node1", + "subject_alt_names": [ + {"type": "urn_ssr_peering", "value": "east-alias"} + ] +} +``` + +The `urn_ssr_peering` type automatically expands the value to `URI:urn:ssr:peering:`. For the full list of supported SAN types, see [Configure Certificate Management](config_custom_certs.md#issue-a-certificate-signing-request). + +**Example: Traditional CN-based identity (single node per router)** + +| Router | `peering-common-name` | `common_name` in CSR | SAN URI | `name` in API | +|---|---|---|---|---| +| combo-east | `east-alias` | `east-alias` | *(not needed)* | `my_peering_cert` | +| combo-west | `west-alias` | `west-alias` | *(not needed)* | `my_peering_cert` | + +**Example: SAN URI identity (HA — unique CN per node)** + +| Router | Node | `peering-common-name` | `common_name` in CSR | SAN URI | `name` in API | +|---|---|---|---|---|---| +| combo-east | node1 | `east-alias` | `combo-east-node1` | `urn:ssr:peering:east-alias` | `my_peering_cert` | +| combo-east | node2 | `east-alias` | `combo-east-node2` | `urn:ssr:peering:east-alias` | `my_peering_cert` | +| combo-west | node1 | `west-alias` | `combo-west-node1` | `urn:ssr:peering:west-alias` | `my_peering_cert` | #### Activating the Certificate in Configuration @@ -196,6 +235,10 @@ When provisioning certificates for an HA router, you must execute the private-ke The same node-scoped pattern applies to the `/certificate-request` and `/certificate` endpoints. The request body — including the `name` field — is identical for both nodes. Consult the Swagger documentation at `https:///api/v1/swagger` for the full per-node endpoint schema. ::: +:::tip Unique Common Names in HA (SSR 7.2.0+) +Because both HA nodes share the same `peering-common-name`, earlier releases required both nodes to use an identical `common_name` in their certificates. Starting in SSR 7.2.0, you can use a [SAN URI](#peering-identity-via-subject-alternative-name-uri-ssr-720) to carry the peering identity, allowing each node to have a unique CN — for example, `combo-east-node1` and `combo-east-node2` — while both certificates include the same `urn:ssr:peering:east-alias` SAN URI. +::: + When two nodes are configured as a redundant pair, the keys are exchanged between nodes. This avoids rekeying on flow migration due to node failures. Keys can be safely exchanged between nodes as the HA sync interfaces are connected point to point over an SSH connection. ### Certificate Replacement or Revocation @@ -210,7 +253,13 @@ When a certificate is revoked, expired, or invalid, the SSR generates an alarm. Peer validation is done whenever a new certificate is added, or peer configuration has changed. When a certificate is received, a cached validation response is used. If configured, the received certificate is validated against the `trusted-ca-certificate` list. -When receiving a certificate from a peer router and performing validation, the receiving router extracts and saves the peer router's public key. This is used for validating the authenticity of any subsequent Peer Key/Rekey requests. +When receiving a certificate from a peer router and performing validation, the receiving router checks the certificate's identity against the peer's configured `peering-common-name` using the following order: + +1. **Common Name (CN) check** — if the certificate's CN matches the peer's `peering-common-name`, the certificate is accepted. +2. **SAN URI fallback (SSR 7.2.0+)** — if the CN does not match, the SSR checks for a `urn:ssr:peering:` SAN URI in the certificate's Subject Alternative Name extension. If found, the certificate is accepted. +3. **Rejection** — if neither the CN nor any SAN URI matches, the certificate is rejected. The behavior depends on the `invalid-certificate-behavior` setting (`fail-soft` or `fail-hard`). + +After successful validation, the receiving router extracts and saves the peer router's public key. This is used for validating the authenticity of any subsequent Peer Key/Rekey requests. ### Requirements @@ -233,7 +282,7 @@ config 2. Configure a unique `peering-common-name` on each router. In a secure environment, the router name should never be sent between routers as plaintext in BFD messages. The `peering-common-name` is a **unique alias per router** that identifies the router and is configured at the router level. When `enhanced-security-key-management` is configured, it is validated against the `peering-common-name` from the certificate, and integrated into the auto-generated adjacencies list for the peers of the router from the neighborhood configuration. :::note -The `peering-common-name` must exactly match the `common_name` field used in the certificate signing request (CSR) generated for that router. See [API Naming Rules](#api-naming-rules) for the full field mapping. +The `peering-common-name` must match either the `common_name` field or a `urn:ssr:peering` SAN URI in the certificate generated for that router. See [API Naming Rules](#api-naming-rules) for the full field mapping. ::: ``` From 5aea61b61ea0e603f81d564fc4c5b9f92dd411f9 Mon Sep 17 00:00:00 2001 From: Chris Date: Fri, 15 May 2026 14:16:14 -0400 Subject: [PATCH 08/16] interim commit --- docs/config_pmtu.mdx | 44 +++++++++++--------------------------------- 1 file changed, 11 insertions(+), 33 deletions(-) diff --git a/docs/config_pmtu.mdx b/docs/config_pmtu.mdx index e05dc112e8..bf166c9d1a 100644 --- a/docs/config_pmtu.mdx +++ b/docs/config_pmtu.mdx @@ -5,9 +5,19 @@ sidebar_label: Path MTU Discovery 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. +| Direction | Port/Proto | Client Payload (bytes) | Server Payload (bytes) | Default Interval | Notes | +| --- | --- | --- | --- | --- | --- | +| bidirectional | 1280/UDP | 2945 | 90 | 600s | Interval is configurable within `path-mtu-discovery/interval`, or disabled `path-mtu-discovery/enabled`. | + +Peering SSR routers will perform path MTU discovery on each peer path between each other. This test is run every ten (10) minutes by default, to adjust in the event of path changes between peering devices. During the test, SSR routers send packets of various sizes to discover the MTU of the path. However, in some government deployments the use of MTU discovery is not possible. + +In order to accommodate these deployments where “ICMP Destination Unreachable - Fragmentation Needed” response messages are not generated (RFC1911 is not followed), three successive non-responses are considered equivalent to ICMP responses for the purposes of driving the algorithm with an inferred MTU. + +The discovered MTU is viewable in the output of `show peers`. + 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: +SSR 7.2.0 introduces two complementary enhancements to address the gaps mentioned above: 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. @@ -74,38 +84,6 @@ For TCP traffic, setting `enforced-mss automatic` on the egress `network-interfa ## 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. From 0f1d27713f6fd235755a8628afce039e7945f227 Mon Sep 17 00:00:00 2001 From: Mike Adams Date: Fri, 15 May 2026 14:22:18 -0400 Subject: [PATCH 09/16] Addressed code review comments --- docs/cert_validation_requirements.md | 2 +- docs/sec_enhanced_key_mgmt.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/cert_validation_requirements.md b/docs/cert_validation_requirements.md index ee0a337e0e..c7d0d88b25 100644 --- a/docs/cert_validation_requirements.md +++ b/docs/cert_validation_requirements.md @@ -113,7 +113,7 @@ Client certificates used for peering are validated as leaf (end-entity) certific | --- | --- | | Signature Algorithm | Must be an [accepted algorithm](#accepted-cryptographic-algorithms). | | Public Key | Must be an [accepted key type and size](#key-requirements). | -| Subject Alternative Name (optional) | Starting in SSR 7.2.0, a `urn:ssr:peering:` SAN URI can be used to carry SVRv2 peering identity as an alternative to the Common Name. See [Enhanced Security Key Management — API Naming Rules](sec_enhanced_key_mgmt.md#api-naming-rules) for details. | +| Subject Alternative Name (optional) | Starting in SSR 7.2.0, a `urn:ssr:peering:` SAN URI can be used to carry SVR peering identity as an alternative to the Common Name. See [Enhanced Security Key Management — API Naming Rules](sec_enhanced_key_mgmt.md#api-naming-rules) for details. | ### Intermediate CA Certificates diff --git a/docs/sec_enhanced_key_mgmt.md b/docs/sec_enhanced_key_mgmt.md index 5eb1becc04..6dd2fef3fa 100644 --- a/docs/sec_enhanced_key_mgmt.md +++ b/docs/sec_enhanced_key_mgmt.md @@ -86,7 +86,7 @@ Consistent naming across all API calls and configuration is critical: | Field | Scope | Rule | |---|---|---| | `name` (in all API requests) | Authority-wide | **Must be identical across all routers and nodes.** In SSR 7.1+, any consistent name may be used. | -| `common_name` (in CSR request) | Per-router / per-node | **Must be unique per router or HA node.** Must match the router's configured `peering-common-name` — either directly in the `common_name` field, or via a `urn:ssr:peering` SAN URI (see below). | +| `common_name` (in CSR request) | Per-router / per-node | **Must be unique per router or HA node.** Must match the router's configured `peering-common-name` — unless a `urn:ssr:peering` SAN URI is used to carry the peering identity instead (see below). | | `peering-common-name` (in config) | Per-router | Unique alias per router. Must match either the `common_name` or a `urn:ssr:peering` SAN URI in that router's certificate. | :::note Legacy Name @@ -257,7 +257,7 @@ When receiving a certificate from a peer router and performing validation, the r 1. **Common Name (CN) check** — if the certificate's CN matches the peer's `peering-common-name`, the certificate is accepted. 2. **SAN URI fallback (SSR 7.2.0+)** — if the CN does not match, the SSR checks for a `urn:ssr:peering:` SAN URI in the certificate's Subject Alternative Name extension. If found, the certificate is accepted. -3. **Rejection** — if neither the CN nor any SAN URI matches, the certificate is rejected. The behavior depends on the `invalid-certificate-behavior` setting (`fail-soft` or `fail-hard`). +3. **Rejection** — if neither the CN nor any SAN URI matches, the certificate is rejected. How the SSR handles the certificate rejection is defined using the `invalid-certificate-behavior` setting (`fail-soft` or `fail-hard`). After successful validation, the receiving router extracts and saves the peer router's public key. This is used for validating the authenticity of any subsequent Peer Key/Rekey requests. From 2d18615da32cd9209e08571f358bce2abca4b093 Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 19 May 2026 10:32:55 -0400 Subject: [PATCH 10/16] restoring updated docusaurus file to 7.2 docs. --- docusaurus.config.js | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 06ad758ec6..1959f84cd3 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -7,9 +7,12 @@ 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 918f72c64437d184c0bb8d45213a9bc13cb327af Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 19 May 2026 10:52:02 -0400 Subject: [PATCH 11/16] renaming file to see whether the mermaid graphic works --- docs/{config_pmtu.mdx => config_pmtu.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{config_pmtu.mdx => config_pmtu.md} (100%) diff --git a/docs/config_pmtu.mdx b/docs/config_pmtu.md similarity index 100% rename from docs/config_pmtu.mdx rename to docs/config_pmtu.md From 9ad0d3305e9d4e6f18250dccd8c3ac2d287e6eeb Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 19 May 2026 11:00:17 -0400 Subject: [PATCH 12/16] link fix --- docs/concepts_machine_communication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts_machine_communication.md b/docs/concepts_machine_communication.md index 9b8196419c..9d34daa9c5 100644 --- a/docs/concepts_machine_communication.md +++ b/docs/concepts_machine_communication.md @@ -89,7 +89,7 @@ In order to accommodate these deployments where “ICMP Destination Unreachable The discovered MTU is viewable in the output of `show peers`. -For additional information, see [Path MTU Discovery](config_pmtu.mdx). +For additional information, see [Path MTU Discovery](config_pmtu.md). ### Secure Vector Routing Traffic From 74cace3ca3d70c2fd5378de05d7de9d183f81edb Mon Sep 17 00:00:00 2001 From: mbaj Date: Tue, 19 May 2026 13:37:40 -0400 Subject: [PATCH 13/16] In order to use the new Docusaurus mermaid syntax the docusaurus.config.js needed to be upgraded to 3.0 syntax and existing mermaid and flowchard jsx code needed to be replaced with the now native mermaid syntax --- docs/_install_interactiveoverview.md | 2 +- docs/bcp_att_avpn_configuration.md | 50 ++++++------ docs/bcp_sdwan_design_guide.md | 2 +- docs/{bcp_tenants.mdx => bcp_tenants.md} | 36 ++++----- docs/cc_fips_downloading_iso.md | 2 +- docs/conductor_upgrade.md | 2 +- docs/config_management_over_forwarding.md | 2 +- docs/intro_basic_conductor_config.md | 2 +- docs/intro_downloading_iso.md | 2 +- docs/intro_installation_bootable_media.mdx | 2 +- docs/intro_installation_legacy.md | 2 +- ...o_install.mdx => intro_otp_iso_install.md} | 76 ++++++++----------- docs/legacy_OTP_install.md | 2 +- docs/onboard_ssr_device_otp.md | 4 +- docs/plugin_sip_alg.md | 4 +- docs/plugin_wireguard.md | 2 +- docusaurus.config.js | 6 +- package.json | 1 - sidebars.js | 2 +- src/components/Flowchart.jsx | 41 ---------- src/theme/Mermaid.js | 15 ---- 21 files changed, 88 insertions(+), 169 deletions(-) rename docs/{bcp_tenants.mdx => bcp_tenants.md} (97%) rename docs/{intro_otp_iso_install.mdx => intro_otp_iso_install.md} (91%) delete mode 100644 src/components/Flowchart.jsx delete mode 100644 src/theme/Mermaid.js diff --git a/docs/_install_interactiveoverview.md b/docs/_install_interactiveoverview.md index ebe6420b14..f15e9e8646 100644 --- a/docs/_install_interactiveoverview.md +++ b/docs/_install_interactiveoverview.md @@ -8,4 +8,4 @@ The steps in this section describe the *interactive conductor installation* from The Conductor installation must be completed before installing a Session Smart Router or routers using the ISO. The same ISO is used for both installations. ::: -To install a router **after** installing and configuring the Conductor, use the [SSR Installation](intro_installation_bootable_media.mdx). The [Router Installation Using OTP](intro_otp_iso_install.mdx) procedure can be used for whitebox and air-gap, conductor-managed network installations. \ No newline at end of file +To install a router **after** installing and configuring the Conductor, use the [SSR Installation](intro_installation_bootable_media.mdx). The [Router Installation Using OTP](intro_otp_iso_install.md) procedure can be used for whitebox and air-gap, conductor-managed network installations. \ No newline at end of file diff --git a/docs/bcp_att_avpn_configuration.md b/docs/bcp_att_avpn_configuration.md index 11a874c4f9..b00d53dc60 100644 --- a/docs/bcp_att_avpn_configuration.md +++ b/docs/bcp_att_avpn_configuration.md @@ -3,8 +3,6 @@ title: AT&T AVPN Configuration sidebar_label: AT&T AVPN Configuration --- -import Mermaid from '@theme/Mermaid'; - This guide is for network engineers and architects using their Session Smart Router to connect to AT&T’s MPLS VPN (AVPN) service. It will cover: - Service class definitions for the various COS queues on the AT&T MPLS network - Strategies for mapping `service` configuration to the COS queues using `service-policy` elements @@ -229,37 +227,37 @@ The base class `service-policy` configurations presented here are derived from t The SSR uses four traffic engineering queues for prioritizing egress traffic during times of congestion or link contention. The general practice of mapping the `traffic-class` assignments (high, medium, low, best-effort) into the various 6COS queues is shown below. - ATT-COS1 - id1(BFD, BGP) -.-> ATT-control - voip-video --> ATT-COS2V - video-streaming --> ATT-COS2V - voip-signaling --> ATT-COS2 - data-mission-critical --> ATT-COS2 - remote-desktop --> ATT-COS2 - management-interactive --> ATT-COS3 - management-m2m --> ATT-COS3 - data-interactive --> ATT-COS3 - data-best-effort --> ATT-COS4 - data-scavenger --> ATT-COS5 - video-streaming-scavenger --> ATT-COS5 - subgraph best-effort +```mermaid +graph LR + voip-audio --> ATT-COS1 + id1(BFD, BGP) -.-> ATT-control + voip-video --> ATT-COS2V + video-streaming --> ATT-COS2V + voip-signaling --> ATT-COS2 + data-mission-critical --> ATT-COS2 + remote-desktop --> ATT-COS2 + management-interactive --> ATT-COS3 + management-m2m --> ATT-COS3 + data-interactive --> ATT-COS3 + data-best-effort --> ATT-COS4 + data-scavenger --> ATT-COS5 + video-streaming-scavenger --> ATT-COS5 + subgraph best-effort ATT-COS5 - end - subgraph low + end + subgraph low ATT-COS4 - end - subgraph medium + end + subgraph medium ATT-COS2V ATT-COS2 ATT-COS3 - end - subgraph high + end + subgraph high ATT-COS1 ATT-control - end -`}/> + end +``` Each AT&T AVPN circuit has a *profile* associated with it (referred to as a "COS Package"), that maps to bandwidth allocations for the various COS queues. These in turn need to be mapped to the four egress traffic engineering queues on the SSR. The COS Package from AT&T is expressed as a set of six numbers (corresponding to the queues), where the first number is the percentage of the circuit bandwidth allocated for COS1, and the remaining five numbers (which sum to 100%) represent the amount of *bandwidth remaining* from the bandwidth not used by COS1. diff --git a/docs/bcp_sdwan_design_guide.md b/docs/bcp_sdwan_design_guide.md index 90e7d46ad5..69ac061029 100644 --- a/docs/bcp_sdwan_design_guide.md +++ b/docs/bcp_sdwan_design_guide.md @@ -89,7 +89,7 @@ There are many considerations with a pod design. In the drawing above, the hando ### Tenancy Design -*Main article: [Tenancy Design](bcp_tenants.mdx)* +*Main article: [Tenancy Design](bcp_tenants.md)* From the discussion with the end customer on segmentation, the definition of tenants should be relatively straight forward. The goal is to create a list of global profiles that can be used for access policies to services. Conceptually, tenancy should not be tied to a location and should be a global construct available whenever we want to classify traffic to a profile when it enters the SSR fabric across the authority (though at times due to business logic defined by the customer, a tenant may reflect a location). At any point in the authority, when traffic ingresses into an SSR, tenancy is applied. Typically this is done by assigning the tenant to the network-interface according to the purpose of the VLAN for which the SSR is the router. For example "POS" for point of sale, "voice" for telephony devices, and "core" for traffic coming from the customer's core network (if no further breakdown of tenancy is required for this traffic). The SSR can also restrict ingress traffic into a tenant further by creating a neighborhood on the network interface. Neighborhoods serve multiple purposes and an additional discussion of neighborhoods will occur in an ensuing section. In the global tenant configuration, this neighborhood may be referenced as a "member" and then CIDR block ranges for source addresses can be defined within this member. In this manner, a shared neighborhood name can be configured on a common LAN network for a site category and the tenant configuration can be updated with the specific list of CIDR ranges that will be used to identify which source IP addresses belong to a particular tenant for traffic coming in on this interface. diff --git a/docs/bcp_tenants.mdx b/docs/bcp_tenants.md similarity index 97% rename from docs/bcp_tenants.mdx rename to docs/bcp_tenants.md index 7658d15201..a3a0ea39c6 100644 --- a/docs/bcp_tenants.mdx +++ b/docs/bcp_tenants.md @@ -3,8 +3,6 @@ title: Tenancy Design sidebar_label: Tenancy Design --- -import Flowchart from '../src/components/Flowchart'; - The *tenant* is one of the foundational data model elements within the Session Smart Router (SSR), and represents a consumer of network *services*. Tenancy is the logical partitioning of a network’s resources, done in the interest of restricting access to network services to only the users and groups for which they’re intended. This document provides an overview of tenancy in the SSR, how it is configured, and provides guidance for modeling the segmentation of a network using the SSR's data modeling language. @@ -41,26 +39,20 @@ As new sessions arrive at an SSR, the router will attempt to classify the source Should none of these result in a definitive determination on the tenant of the source of this session request, the session is associated with the *global tenant* (see the section on "Special Tenants" for more information on the global tenant). Once the tenant has been identified – either as a specific tenant, or as the global tenant – this acts as a filter into the SSR’s FIB. Only the routes associated with that tenant are available to that user group. While this somewhat resembles the way a legacy router uses VRFs to create separate RIBs and FIBs, the segment by *tenant* is pervasive among all routers within an Authority by design, and is applied ubiquitously among all varieties of networks: public IP space, private, cloud, IPv4, IPv6, etc. -start: Packet Arrives - metadata=>condition: Packet has metadata? - int=>condition: Interface has a tenant? - nh=>condition: Neighborhood-based tenant? - tm=>operation: Tenant taken from metadata - ti=>operation: Tenant taken from interface - th=>operation: Tenant taken from neighborhood - global=>operation: Tenant assigned as "global" - e=>end: Proceed to FIB lookup - st->metadata - metadata(no)->int - metadata(yes,right)->tm->e - int(yes,right)->ti->e - int(no)->nh - nh(yes,right)->th->e - nh(no)->global->e - `} -/> +```mermaid +flowchart TD + st([Packet Arrives]) --> metadata{Packet has metadata?} + metadata -->|no| int{Interface has a tenant?} + metadata -->|yes| tm[Tenant taken from metadata] + tm --> e([Proceed to FIB lookup]) + int -->|yes| ti[Tenant taken from interface] + ti --> e + int -->|no| nh{Neighborhood-based tenant?} + nh -->|yes| th[Tenant taken from neighborhood] + th --> e + nh -->|no| gl["Tenant assigned as "global""] + gl --> e +``` #### Viewing a Router's Tenancy diff --git a/docs/cc_fips_downloading_iso.md b/docs/cc_fips_downloading_iso.md index bef726db73..a6ada033e3 100644 --- a/docs/cc_fips_downloading_iso.md +++ b/docs/cc_fips_downloading_iso.md @@ -11,7 +11,7 @@ Juniper Session Smart Networking provides the following workflows for the compli - **Package-based ISO:** This ISO offers multiple local installation methods. - **One Touch Provisioning (OTP)** is the default and preferred method of Router installation. OTP sets up DHCP on all interfaces and boots a Web Server GUI. After installing the Conductor and configuring routers through the Conductor, the OTP quickstart process will install and configure the router. See the following procedures for OTP installation steps: - - [Router Installation Using OTP](intro_otp_iso_install.mdx) + - [Router Installation Using OTP](intro_otp_iso_install.md) - [Quickstart from the OTP ISO](intro_install_quickstart_otpiso.md) - **Interactive:** For Conductor installations and bespoke deployments where customized platform configuration is necessary, an interactive mode exists. Installation is done using the serial console. An interactive session is started to configure network interfaces, passwords, node name and type, and conductor IP (if applicable) before the SSR software is started. diff --git a/docs/conductor_upgrade.md b/docs/conductor_upgrade.md index ed102a0161..b3e3925880 100644 --- a/docs/conductor_upgrade.md +++ b/docs/conductor_upgrade.md @@ -130,7 +130,7 @@ While the linux shell is available for upgrading the conductor, it is advised to ## Next Steps -See [Router Interactive Installation](intro_installation_bootable_media.mdx) or [Router Installation Using OTP](intro_otp_iso_install.mdx) for steps to install your routers. +See [Router Interactive Installation](intro_installation_bootable_media.mdx) or [Router Installation Using OTP](intro_otp_iso_install.md) for steps to install your routers. If your deployment will take advantage of Mist Telemetry, see [Enable WAN Assurance on the Conductor](config_wan_assurance.md#enable-wan-assurance-on-the-conductor) for those next steps. diff --git a/docs/config_management_over_forwarding.md b/docs/config_management_over_forwarding.md index 632e6ea441..336e3fdc19 100644 --- a/docs/config_management_over_forwarding.md +++ b/docs/config_management_over_forwarding.md @@ -154,4 +154,4 @@ exit ### User Defined Services -For any other service not defined by the default management services list, the user can configure a _service_ to best suit their needs. It is necessary to configure the [_internal_](bcp_tenants.mdx#the-internal-tenant) tenant within the `access-policy` of the service to allow traffic originating from the Linux host. +For any other service not defined by the default management services list, the user can configure a _service_ to best suit their needs. It is necessary to configure the [_internal_](bcp_tenants.md#the-internal-tenant) tenant within the `access-policy` of the service to allow traffic originating from the Linux host. diff --git a/docs/intro_basic_conductor_config.md b/docs/intro_basic_conductor_config.md index de18319278..50ea6f83b9 100644 --- a/docs/intro_basic_conductor_config.md +++ b/docs/intro_basic_conductor_config.md @@ -44,5 +44,5 @@ In the steps below, we provide an example tenant name, _corp_, which is used in 4. Return to the top level. 5. At the top of the screen, select VALIDATE and then COMMIT. -For more information about Tenancy, please see [Tenancy Design](bcp_tenants.mdx). +For more information about Tenancy, please see [Tenancy Design](bcp_tenants.md). For more information about configuring and deploying conductors, please see [conductor Deployment](bcp_conductor_deployment.md). diff --git a/docs/intro_downloading_iso.md b/docs/intro_downloading_iso.md index e55d9b3ed4..6f4885ab32 100644 --- a/docs/intro_downloading_iso.md +++ b/docs/intro_downloading_iso.md @@ -23,7 +23,7 @@ For users installing *earlier, package-based versions of the SSR software*, the This ISO also provides different local installation methods. - **One Touch Provisioning (OTP)** is the default and preferred method of installation. OTP sets up DHCP on all interfaces and boots a Web Server GUI. After installing the Conductor and configuring routers through the Conductor, the OTP bootstrap process will install and configure the router. See the following procedures for OTP installation steps: - - [Router Installation Using OTP](intro_otp_iso_install.mdx) + - [Router Installation Using OTP](intro_otp_iso_install.md) - [Quickstart from the OTP ISO](intro_install_quickstart_otpiso.md) - **Interactive:** Beginning with SSR version 6.3.0, the use of the interactive installer is not supported, nor necessary. Software installation and upgrade activities are supported from the GUI or PCLI. With software versions earlier than 6.3.0, upgrading the SSR software on a conductor or router that is managed by a conductor using the interactive installer may result in the system becoming unresponsive. For this reason it is highly recommended that upgrades be performed through the conductor UI. For a new installation of a conductor using software prior to 6.3.0, the interactive method can be used. diff --git a/docs/intro_installation_bootable_media.mdx b/docs/intro_installation_bootable_media.mdx index b78e38b68c..8e0b181ec2 100644 --- a/docs/intro_installation_bootable_media.mdx +++ b/docs/intro_installation_bootable_media.mdx @@ -14,7 +14,7 @@ The steps in this section describe the *interactive conductor installation* from The Conductor installation must be completed before installing a Session Smart Router or routers using the ISO. The same ISO is used for both installations. ::: -To install a router **after** installing and configuring the Conductor, use the [SSR Installation](intro_installation_bootable_media.mdx). The [Router Installation Using OTP](intro_otp_iso_install.mdx) procedure can be used for whitebox and air-gap, conductor-managed network installations. +To install a router **after** installing and configuring the Conductor, use the [SSR Installation](intro_installation_bootable_media.mdx). The [Router Installation Using OTP](intro_otp_iso_install.md) procedure can be used for whitebox and air-gap, conductor-managed network installations. :::important If you are installing SSR Version 6.3.x, use the [Universal ISO Installation process](intro_installation_univ-iso.md). diff --git a/docs/intro_installation_legacy.md b/docs/intro_installation_legacy.md index 294fd3c7ad..4b77987171 100644 --- a/docs/intro_installation_legacy.md +++ b/docs/intro_installation_legacy.md @@ -27,7 +27,7 @@ The examples listed in this guide generally prefer running commands as a non-roo - [Perform the Interactive ISO installation](intro_installation_bootable_media.mdx) - [Install a Conductor](install_conductor_overview.md) - [Create the Router configuration with the Conductor](intro_basic_router_config.md) or [Import a Configuration](single_conductor_config.md) - - [Install the Router using the OTP ISO](intro_otp_iso_install.mdx) or [Install the Router using the Interactive Installation](intro_installation_bootable_media.mdx) + - [Install the Router using the OTP ISO](intro_otp_iso_install.md) or [Install the Router using the Interactive Installation](intro_installation_bootable_media.mdx) A Mist-redirect ZTP process for Conductor-managed deployments is supported on Juniper branded hardware devices - the SSR1x0/1x00. See [Onboard an SSR Device to a Conductor](onboard_ssr_to_conductor.md) for details about this process. diff --git a/docs/intro_otp_iso_install.mdx b/docs/intro_otp_iso_install.md similarity index 91% rename from docs/intro_otp_iso_install.mdx rename to docs/intro_otp_iso_install.md index 90c397fc54..6e54d1b294 100644 --- a/docs/intro_otp_iso_install.mdx +++ b/docs/intro_otp_iso_install.md @@ -3,8 +3,6 @@ title: Router Installation Using OTP sidebar_label: Router Installation Using OTP --- -import Flowchart from '../src/components/Flowchart'; - :::important If you are installing SSR Version 6.3.x, use the [Universal ISO Installation process](intro_installation_univ-iso.md). ::: @@ -178,50 +176,36 @@ Any stdout/stderr output generated from the scriptlets is logged in `/var/log/12 ### Bootstrapping Flow Chart The diagram below shows the procedure the Bootstrap utility follows during the first boot-up of the platform after the ISO installation completes. -start: Start - bs=>operation: Check for Pre-Bootstrap Scriptlet - usb1=>condition: On USB? - def1=>condition: Default? - es=>inputoutput: Execute Pre-Bootstrap Scriptlet - smh=>operation: Set Minion ID\nSet Hostname\nSynchronize Clock - sfd=>operation: Set 128T Factory Defaults - usb2=>condition: On USB? - def2=>condition: Default? - rest=>condition: REST get? - aq=>inputoutput: Apply quickstart.txt - aotpd=>inputoutput: Apply OTP Defaults - ist=>operation: Setup IFCFG\nEnable salt-minion\nEnable 128T - pbs=>operation: Check for Post-Bootstrap Scriptlet - usb3=>condition: On USB? - def3=>condition: Default? - es2=>inputoutput: Execute Post-Bootstrap Scriptlet - fin=>operation: Finalize - wbr=>subroutine: Write Bootstrap Report - reb=>operation: Reboot - e=>end: End - st->bs->usb1 - usb1(no)->def1 - usb1(yes)->es - def1(yes)->es - def1(no)->smh - es->smh - smh->sfd->usb2 - usb2(no, right)->def2 - usb2(yes, right)->aq - def2(yes)->aq - def2(no)->rest - rest(no)->aotpd - rest(yes)->aq->ist - aotpd->ist->pbs->usb3 - usb3(yes)->es2 - usb3(no)->def3 - def3(yes)->es2->fin - def3(no)->fin - fin->wbr->reb->e - `} -/> +```mermaid +flowchart TD + st([Start]) --> bs[Check for Pre-Bootstrap Scriptlet] + bs --> usb1{On USB?} + usb1 -->|yes| es[/Execute Pre-Bootstrap Scriptlet/] + usb1 -->|no| def1{Default?} + def1 -->|yes| es + def1 -->|no| smh + es --> smh["Set Minion ID
Set Hostname
Synchronize Clock"] + smh --> sfd[Set 128T Factory Defaults] + sfd --> usb2{On USB?} + usb2 -->|yes| aq[/Apply quickstart.txt/] + usb2 -->|no| def2{Default?} + def2 -->|yes| aq + def2 -->|no| rest{REST get?} + rest -->|yes| aq + rest -->|no| aotpd[/Apply OTP Defaults/] + aq --> ist["Setup IFCFG
Enable salt-minion
Enable 128T"] + aotpd --> ist + ist --> pbs[Check for Post-Bootstrap Scriptlet] + pbs --> usb3{On USB?} + usb3 -->|yes| es2[/Execute Post-Bootstrap Scriptlet/] + usb3 -->|no| def3{Default?} + def3 -->|yes| es2 + def3 -->|no| fin[Finalize] + es2 --> fin + fin --> wbr[[Write Bootstrap Report]] + wbr --> reb[Reboot] + reb --> e([End]) +``` ### QuickStart File via REST diff --git a/docs/legacy_OTP_install.md b/docs/legacy_OTP_install.md index e8929fbd86..ba6a896252 100644 --- a/docs/legacy_OTP_install.md +++ b/docs/legacy_OTP_install.md @@ -7,7 +7,7 @@ The steps in this section describe installing the legacy Interactive ISO from bo :::note The Conductor installation must be completed before installing a router or routers using the OTP ISO. ::: -See [Installing Using the One Touch Provisioning ISO](intro_otp_iso_install.mdx) for details to install complex router configurations **after** installing and configuring the Conductor. +See [Installing Using the One Touch Provisioning ISO](intro_otp_iso_install.md) for details to install complex router configurations **after** installing and configuring the Conductor. ## Prerequisites diff --git a/docs/onboard_ssr_device_otp.md b/docs/onboard_ssr_device_otp.md index d261587fa1..70f19c20ee 100644 --- a/docs/onboard_ssr_device_otp.md +++ b/docs/onboard_ssr_device_otp.md @@ -79,7 +79,7 @@ Use the process specific to your device to complete the re-imaging process. 2. From the boot menu, enter the boot device number corresponding to the USB, and press Enter. ![Select Boot Device](/img/onboard_otp_boot_device.png) -3. When the USB installer boot menu is displayed, follow the [Installing SSR Using OTP](intro_otp_iso_install.mdx#installing-ssr-using-one-touch-provisioning-otp) instructions to complete the installation process. +3. When the USB installer boot menu is displayed, follow the [Installing SSR Using OTP](intro_otp_iso_install.md#installing-ssr-using-one-touch-provisioning-otp) instructions to complete the installation process. #### SSR1000 Series Devices @@ -92,5 +92,5 @@ Use the process specific to your device to complete the re-imaging process. ![Boot Override list](/img/1x00_boot-override.png) 4. Press Enter to confirm boot from the USB device. -5. When the USB installer boot menu is displayed, follow the [Installing SSR Using OTP](intro_otp_iso_install.mdx#installing-ssr-using-one-touch-provisioning-otp) instructions to complete the installation process. +5. When the USB installer boot menu is displayed, follow the [Installing SSR Using OTP](intro_otp_iso_install.md#installing-ssr-using-one-touch-provisioning-otp) instructions to complete the installation process. diff --git a/docs/plugin_sip_alg.md b/docs/plugin_sip_alg.md index 2cd3f2d545..ab00c1d230 100644 --- a/docs/plugin_sip_alg.md +++ b/docs/plugin_sip_alg.md @@ -124,7 +124,7 @@ authority exit ``` -The service `sip-outbound-dc1` captures all SIP UDP traffic towards port 5060 originating from the [`_internal_` tenant](bcp_tenants.mdx#the-internal-tenant). This is a special tenant associated with the SFC KNIs. The `sip-service > outbound` for the sip-alg configuration refers to this user configured service in the above example. In this process, the plugin will inherit all the address and transport configuration from this _service_, combined with the defined _access-policy_ on the plugin, will generate the configuration for SIP traffic received on the lan tenant. The `ingress-service-policy` can be used to provide a custom policy to be applied to the generated service. More details on service policy design can be found [here](bcp_service_and_service_policy_design.md#service-policy) +The service `sip-outbound-dc1` captures all SIP UDP traffic towards port 5060 originating from the [`_internal_` tenant](#the-internal-tenant). This is a special tenant associated with the SFC KNIs. The `sip-service > outbound` for the sip-alg configuration refers to this user configured service in the above example. In this process, the plugin will inherit all the address and transport configuration from this _service_, combined with the defined _access-policy_ on the plugin, will generate the configuration for SIP traffic received on the lan tenant. The `ingress-service-policy` can be used to provide a custom policy to be applied to the generated service. More details on service policy design can be found [here](bcp_service_and_service_policy_design.md#service-policy) :::note If the egress service has no transport configured, the plugin assumes the default SIP port of `5060` for both TCP and UDP. @@ -193,7 +193,7 @@ authority exit ``` -The service `sip-inbound-pbx` captures all SIP UDP traffic towards port 5060 originating from the [`_internal_` tenant](bcp_tenants.mdx#the-internal-tenant). This is a special tenant associated with the SFC KNIs. The `sip-service > inbound` for the sip-alg configuration refers to this user configured service in the above example. In this process, the plugin will inherit all the address and transport configuration from this _service_, combined with the defined _access-policy_ on the plugin, will generate the configuration for SIP traffic received on the `datacenter` tenant. The `ingress-service-policy` can be used to provide a custom policy to be applied to the generated service. More details on service policy design can be found [here](bcp_service_and_service_policy_design.md#service-policy) +The service `sip-inbound-pbx` captures all SIP UDP traffic towards port 5060 originating from the [`_internal_` tenant](bcp_tenants.md#the-internal-tenant). This is a special tenant associated with the SFC KNIs. The `sip-service > inbound` for the sip-alg configuration refers to this user configured service in the above example. In this process, the plugin will inherit all the address and transport configuration from this _service_, combined with the defined _access-policy_ on the plugin, will generate the configuration for SIP traffic received on the `datacenter` tenant. The `ingress-service-policy` can be used to provide a custom policy to be applied to the generated service. More details on service policy design can be found [here](bcp_service_and_service_policy_design.md#service-policy) :::note If the ingress service has no transport configured, the plugin assumes the default SIP port of `5060` for both TCP and UDP. diff --git a/docs/plugin_wireguard.md b/docs/plugin_wireguard.md index aa18203989..8f0bc6bd1c 100644 --- a/docs/plugin_wireguard.md +++ b/docs/plugin_wireguard.md @@ -84,7 +84,7 @@ exit ## Services and Tenants with Wireguard -Configuration of a wireguard profile on an SSR interface does **not** provide access to network services. It simply allows the endpoint to connect to the router using wireguard for secure transport, and all sessions will still be subject to the rules of [tenants and services](concepts_glossary.md#service-layer). To facilitate network tenancy being given to traffic coming from wireguard peers, a profile is configured with a neighborhood. The neighborhood in the wireguard profile will function as a named Layer 3 network, and used in defining [neighborhood based tenancy](bcp_tenants.mdx#per-neighborhood-tenancy) to provide access to services. +Configuration of a wireguard profile on an SSR interface does **not** provide access to network services. It simply allows the endpoint to connect to the router using wireguard for secure transport, and all sessions will still be subject to the rules of [tenants and services](concepts_glossary.md#service-layer). To facilitate network tenancy being given to traffic coming from wireguard peers, a profile is configured with a neighborhood. The neighborhood in the wireguard profile will function as a named Layer 3 network, and used in defining [neighborhood based tenancy](bcp_tenants.md#per-neighborhood-tenancy) to provide access to services. :::tip If you do not have a pre-defined tenant to use for wireguard endpoints, you can optionally configure a `tenant` in the profile, and one will be automatically generated for you. diff --git a/docusaurus.config.js b/docusaurus.config.js index 1959f84cd3..d48f1f277b 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -1,4 +1,4 @@ -module.exports = { +const config = { title: 'SSN Docs', tagline: 'The documentation source for the Session Smart Networking Platform', url: 'https://docs.128technology.com', @@ -117,7 +117,7 @@ module.exports = { }; if (process.env.OFFLINE_DOCS) { - module.exports.themeConfig.announcementBar = { + config.themeConfig.announcementBar = { id: 'offline_docs', content: 'You are viewing a local version of this documentation. ' + @@ -127,3 +127,5 @@ if (process.env.OFFLINE_DOCS) { isCloseable: true, }; } + +module.exports = config; diff --git a/package.json b/package.json index d8699eac9d..bcb303ba04 100644 --- a/package.json +++ b/package.json @@ -28,7 +28,6 @@ "prism-react-renderer": "^2.4.1", "react": "^19.2.6", "react-dom": "^19.2.6", - "react-simple-flowchart": "^1.2.4", "react-table": "^7.0.0" }, "devDependencies": { diff --git a/sidebars.js b/sidebars.js index 44cd4cf22e..56911b1a15 100644 --- a/sidebars.js +++ b/sidebars.js @@ -176,7 +176,7 @@ module.exports = { "label": "Router Installation", "items": [ "intro_installation_bootable_media", - "intro_basic_router_config", + "intro_basic_router_config", "intro_otp_iso_install", "intro_install_quickstart_otpiso", "onboard_ssr_to_conductor", diff --git a/src/components/Flowchart.jsx b/src/components/Flowchart.jsx deleted file mode 100644 index 6f758111fd..0000000000 --- a/src/components/Flowchart.jsx +++ /dev/null @@ -1,41 +0,0 @@ -import React from 'react'; -import PropTypes from 'prop-types'; -import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment'; - -class Flowchart extends React.Component { - constructor(props) { - super(props); - - this.state = {}; - } - - componentDidMount() { - if (ExecutionEnvironment.canUseDOM) { - this.setState({ - Flowchart: require('react-simple-flowchart').default, - }); - } - } - - render() { - const {Flowchart} = this.state; - const {chartCode, scale = 0.7} = this.props; - - if (!ExecutionEnvironment.canUseDOM || !Flowchart) { - return
; - } - - return ( -
- -
- ); - } -} - -Flowchart.propTypes = { - chartCode: PropTypes.string.isRequired, - scale: PropTypes.number, -}; - -export default Flowchart; diff --git a/src/theme/Mermaid.js b/src/theme/Mermaid.js deleted file mode 100644 index 7d6376db3e..0000000000 --- a/src/theme/Mermaid.js +++ /dev/null @@ -1,15 +0,0 @@ -import React, { useEffect } from "react"; -import mermaid from "mermaid"; - -mermaid.initialize({ - startOnLoad: true -}); - -const Mermaid = ({ chart }) => { - useEffect(() => { - mermaid.contentLoaded(); - }, []); - return
{chart}
; -}; - -export default Mermaid; \ No newline at end of file From f827e042e30307e9fb596b5e9a9ce45dc42bd018 Mon Sep 17 00:00:00 2001 From: mbaj Date: Tue, 19 May 2026 14:07:41 -0400 Subject: [PATCH 14/16] Fix broken link after file name change --- docs/plugin_sip_alg.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugin_sip_alg.md b/docs/plugin_sip_alg.md index ab00c1d230..8de4c9ffc0 100644 --- a/docs/plugin_sip_alg.md +++ b/docs/plugin_sip_alg.md @@ -124,7 +124,7 @@ authority exit ``` -The service `sip-outbound-dc1` captures all SIP UDP traffic towards port 5060 originating from the [`_internal_` tenant](#the-internal-tenant). This is a special tenant associated with the SFC KNIs. The `sip-service > outbound` for the sip-alg configuration refers to this user configured service in the above example. In this process, the plugin will inherit all the address and transport configuration from this _service_, combined with the defined _access-policy_ on the plugin, will generate the configuration for SIP traffic received on the lan tenant. The `ingress-service-policy` can be used to provide a custom policy to be applied to the generated service. More details on service policy design can be found [here](bcp_service_and_service_policy_design.md#service-policy) +The service `sip-outbound-dc1` captures all SIP UDP traffic towards port 5060 originating from the [`_internal_` tenant](bcp_tenants.md#the-internal-tenant). This is a special tenant associated with the SFC KNIs. The `sip-service > outbound` for the sip-alg configuration refers to this user configured service in the above example. In this process, the plugin will inherit all the address and transport configuration from this _service_, combined with the defined _access-policy_ on the plugin, will generate the configuration for SIP traffic received on the lan tenant. The `ingress-service-policy` can be used to provide a custom policy to be applied to the generated service. More details on service policy design can be found [here](bcp_service_and_service_policy_design.md#service-policy) :::note If the egress service has no transport configured, the plugin assumes the default SIP port of `5060` for both TCP and UDP. From 81ae4b24fa5c01ff9ef54e60dcc14da311f66096 Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 19 May 2026 16:10:08 -0400 Subject: [PATCH 15/16] adding release notes doc and new features for swift beta --- docs/config_bgp.md | 14 +++--- docs/release_notes_128t_7.2.md | 88 ++++++++++++++++++++++++++++++++++ docs/sec_enhanced_key_mgmt.md | 2 +- 3 files changed, 95 insertions(+), 9 deletions(-) create mode 100644 docs/release_notes_128t_7.2.md diff --git a/docs/config_bgp.md b/docs/config_bgp.md index 4d96c6df90..963d9fd8ff 100644 --- a/docs/config_bgp.md +++ b/docs/config_bgp.md @@ -1025,6 +1025,7 @@ There is one additional field which needs to be set in route reflector's BGP con When the route reflector sends routes to the clients, by default it doesn't modify the next-hop. An outbound policy can be used to change the next-hop in these routes to that of the route reflector, if desired. In such instances, another option, which is turned off by default, needs to be set in the route reflector's BGP config: `Route Reflector Allow Outbound Policy = TRUE`. ### BGP Confederations + When configuring iBGP, the **Confederation** feature may be helpful when dealing with an enormous autonomous system. This feature allows you to break up the AS into smaller sub-autonomous systems. Confederation can be directly configured under the routing protocol element. Here, 65535 is the **confederation identifier AS number** and, 1100 and 2200 are the **member AS** numbers of that confederation AS. ``` @@ -1042,9 +1043,11 @@ admin@branchoffice1.seattlesite1 (routing-protocol[type=bgp])# exit 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. -::: +### Version History + +| Release | Modification | +|---|---| +| 7.2.0 | Feature introduced. | ### PCLI @@ -1177,8 +1180,3 @@ Response: 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/docs/release_notes_128t_7.2.md b/docs/release_notes_128t_7.2.md new file mode 100644 index 0000000000..c1f8f9a188 --- /dev/null +++ b/docs/release_notes_128t_7.2.md @@ -0,0 +1,88 @@ +--- +title: SSR 7.2 Release Notes +sidebar_label: '7.2' +--- + +The SSR has moved away from the historical package-based delivery to an image-based delivery. As such, it is strongly suggested that you revisit your "standard" procedures for installation and upgrade of SSR Software. + +Beginning with SSR v6.3.0, the use of the interactive installer is not supported, or necessary. Software installation and upgrade activities are supported from the Web Interface or the Command Line Interface. + +With the image-based ISO delivered beginning with version 6.3.0, the manual installation process no longer supports the `initialize128t` command. + +Initializing devices as a conductor or conductor-managed router is easily accomplished from the GUI using the [Initialize Your Device - Web Workflow](initialize_u-iso_device.md), or from the CLI using the the `initialize conductor` and `initialize conductor-managed` commands described in the [Initialize Your Device - Advanced Workflow](initialize_u-iso_adv_workflow.md#initialize-a-conductor) documentation. + +### Installation from ISO + +When installing SSR V6.3.0 or newer on a new system, use the image-based ISO - identified by the filename prefix "SSR": `SSR-6.3.0-107.r1.el7.x86_64.ibu-v1.iso`. Installation documentation for the image-based process can be found in the [Image-based ISO Installation Overview](intro_installation_univ-iso.md). + +Offline mode conductor and router upgrades to image-based installations are detailed in the [Single-Version 6.3.0 Upgrade](upgrade_restricted_access.md#single-version-630-upgrade) instructions. + + +### Upgrade Considerations + +:::important +Before upgrading please review the [**Upgrade Considerations**](intro_upgrade_considerations.md) and the [**Rolling Back Software**](intro_rollback.md) pages. Several modifications have been made to the process for verifying configurations, which will impact existing configurations. +::: + +:::important +After installing / upgrading to SSR 7.1.3, downgrading *to an earlier version* of SSR software where Configuration Integrity (CI) is not available is NOT supported. + +Rollback to the previously installed version of software *is* supported. +::: + +:::warning +An issue has been identified involving the use of the HA Sync Redundancy Plugin with SSR 7.0.0, which prevents proper functioning of the plugin. If you use the HA Plugin in your SSR deployment, it is not advised to upgrade at this time. The issue is being investigated and will be resolved in a future release. +::: + +**7.0.1 Conductor Upgrades** + +If you are upgrading a conductor that is currently installed with version 6.3.4 or lower, and you wish to upgrade to version 7.0.1 or higher, you must first upgrade the conductor to any version of the 6.3.x software, including and higher than 6.3.5. + +Routers running SSR software versions earlier than 6.3.5 cannot connect to conductors running SSR software version 7.0.1 and higher. A transitional step is required to enable routers running versions earlier than 6.3.5 (6.0.x, 6.1.x, 6.2.x, 6.3.4 and lower) to communicate with a conductor running 7.0.1+. + +1. Upgrade the conductor to any version of the 6.3.x software, including and higher than 6.3.5. +2. Upon completion of the install, allow all managed routers to connect and reach the **Synchronized** state. + The new keying requirements that are part of 6.3.5+ are loaded onto the routers during synchronization. These are required for routers to communicate with a 7.0.1+ conductor. If the routers do not reach the synchronized state, those routers will not be able to communicate with the 7.0.1+ conductor. +3. Once the routers are synchronized, you may upgrade the conductor to 7.0.1. All synchronized routers, regardless of version, will be able to communicate with the upgraded conductor. The routers are not required to upgrade to 7.0.1 or to 6.3.5. + +If your conductor is currently running SSR version 6.3.5+, you may upgrade to 7.0.1 normally. + +**VM Upgrades 6.2.x to 7.x** + +Users upgrading a virtual machine, including those on AWS or Azure, previously installed with package-based SSR releases (6.2 and prior on Conductor-managed deployments only) should be aware of the following: + +Due to changes in the base SSR/Linux OS in 7.X, interface naming behavior has changed for virtual machines. Older SSR versions using earlier versions of the SSR OS may have named Linux interfaces with the `ethX` naming convention. Interfaces in 7.X and above use the Linux predictable interface naming convention as seen in SSR hardware installs. This change in interface naming could prevent existing Linux interface configurations not to apply to the `ethX`-named interface. This applies to interfaces configured directly in Linux, such as dedicated management interfaces, and **not** interfaces configured via SSR configuration. + +This issue is currently being addressed by engineering. However, if your deployment requires an upgrade to 7.X on a VM configured with interfaces using the `ethX` naming convention, please ensure that console access is available, as manual updates to the Linux interface configuration may be required. + +**System Disk Considerations** + +As mentioned above, during the upgrade to an image-based installation, existing systems will go through a conversion process to support image-based delivery. This process involves resizing the existing disk partition to support writing a new disk image to the remaining disk space. As such, the usable disk space seen after this conversion will be approximately halved. The system will automatically detect if there is not enough usable disk space on the existing drive to support this partition resizing and, if so, will trigger an upgrade failure. Even if the conversion is successful and the upgrade succeeds, users may note that the system is experiencing disk space alarms after the upgrade due to the reduction in overall capacity. It is suggested to remove unnecessary large files from systems before upgrading. Old saved tech-support-info archives (check for tar.gz or zip files in `/var/log/128technology`) and uploaded ISO images are frequent contributors to used disk space and should be manually deleted. + +In certain scenarios, existing cloud routers may have been installed from images that did not use LVM for partitions. For these systems, the automatic resizing of disk partitions will fail and they cannot be upgraded. It is suggested to rebuild these instances from the official SSR BYOL image for either [AWS](intro_installation_quickstart_byol_conductor_aws.md) or [Azure](intro_installation_byol_azure_conductor.md). + +When the conductor is initially upgraded to an image-based installation, it will be upgraded as a package-based system. This is because the system does not understand how to handle image-based delivery until it is running 6.3 software. Once the conductor is running 6.3 all router upgrades will be treated as image-based upgrades and any subsequent conductor upgrade will be treated as image-based. Therefore, it is possible that issues related to disk usage on conductor may not arise until a subsequent upgrade of the conductor beyond the initial step to 6.3. + +**Offline-Mode: Upgrading 6.3.x Conductor Deployments to 6.3.x+** + +An issue has been identified that may be observed in conductor deployments running version 6.3.x software, when attempting to upgrade from one 6.3.x patch release to another. This results in the message, “SSR firmware upgrade failed for the local node: SSR upgrade failed after reboot”. To work around this, run `request system software upgrade installation-service` from the command line of the Conductor, after importing the image-based ISO. Once complete, perform the full system upgrade from the Web interface. This issue will be resolved in a future release. + +**Offline-Mode: Onboarding Routers Running older SSR Software to a 6.3.x Conductor** + +An issue has been identified when onboarding SSR routers installed with older versions of software (such as 5.4.4) to Conductors running 6.3.x, when running in offline-mode. In some cases, certain software packages are not available to be installed during onboarding. To work around this issue, import the **package-based** (the "128T" prefixed) ISO for the current conductor version onto the conductor. This provides the necessary software packages to complete the onboarding process. This issue will be resolved in a future release. + +## Release 7.2.0-10r1 + +**Beta Release Date:** May 21, 2026 + +### New Features + +- **Adaptive PMTU Change Handling for Long-Lived Sessions:** The SSR performs Path MTU Discovery (PMTUD) along the overlay to determine the correct maximum transmission unit (MTU) for each peer path. Devices in the underlay may report an ICMP Destination Unreachable / Fragmentation Needed (type 3, code 4) error to indicate they could not forward a packet due to an undersized MTU. With 7.2.0, the SSR updates the affected overlay flow and generates a corrected packet toward the original packet sender, allowing the sender to adjust its segment size. The flow which was traversed to trigger the response from the underlay is now updated to use the new updated MTU. For more information, see [Path MTU Discovery](config_pmtu.md). +------ +- **I95-61066 Simplified Interface Naming:** Removed the platform restriction (SSR400/SSR440 only) that prevented the ability to configure forwarding device-interfaces via Linux `interface-name`. `interface-name` can now be used as a device identifier on all physical and virtual SSR platforms for both forwarding and non-forwarding interfaces, enabling stable, name-based NIC configuration for cloud VMs, bare-metal servers, and purpose-built hardware alike. +------ +- **I95-61467 Show filtered-routes in `show bgp` output:** 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. For more information, see [Viewing Filtered BGP Routes](config_bgp.md#viewing-filtered-bgp-routes). +------ +- **I95-64645 Certificate Management - CSR Improvements:** Starting in SSR 7.2.0, the peering identity can be carried in a Subject Alternative Name (SAN) URI extension instead of the Common Name (CN). This is especially useful in **HA deployments**, where both nodes in a router share the same `peering-common-name` but enterprise PKI policies require unique CNs per certificate. See [Enhanced Security Key Management — API Naming Rules](sec_enhanced_key_mgmt.md#peering-identity-via-subject-alternative-name-uri) for details. +------ +- **I95-64845 Add Missing Audit Events for Certificate APIs:** Addes several audit events and logs for certificate activity. See [Audit Events and Logging](sec-cert-based-encrypt.md#audit-eventslogging) for additional information. diff --git a/docs/sec_enhanced_key_mgmt.md b/docs/sec_enhanced_key_mgmt.md index 6dd2fef3fa..b9658b56c7 100644 --- a/docs/sec_enhanced_key_mgmt.md +++ b/docs/sec_enhanced_key_mgmt.md @@ -93,7 +93,7 @@ Consistent naming across all API calls and configuration is critical: In SSR 7.0.x, the `name` field was required to be `custom_ssr_peering` (a reserved name). This is no longer required in SSR 7.1+. If no certificate is configured, the SSR will fall back to searching for certificates named `custom_ssr_peering` on disk for backward compatibility. ::: -##### Peering Identity via Subject Alternative Name URI (SSR 7.2.0+) +#### Peering Identity via Subject Alternative Name URI Starting in SSR 7.2.0, the peering identity can be carried in a Subject Alternative Name (SAN) URI extension instead of the Common Name (CN). This is especially useful in **HA deployments**, where both nodes in a router share the same `peering-common-name` but enterprise PKI policies require unique CNs per certificate. From 3379aa0e6e1cee1ae99c2643bad690894d4c79f9 Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 19 May 2026 16:44:40 -0400 Subject: [PATCH 16/16] broken link fix --- docs/sec_enhanced_key_mgmt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sec_enhanced_key_mgmt.md b/docs/sec_enhanced_key_mgmt.md index b9658b56c7..6f601207dd 100644 --- a/docs/sec_enhanced_key_mgmt.md +++ b/docs/sec_enhanced_key_mgmt.md @@ -236,7 +236,7 @@ The same node-scoped pattern applies to the `/certificate-request` and `/certifi ::: :::tip Unique Common Names in HA (SSR 7.2.0+) -Because both HA nodes share the same `peering-common-name`, earlier releases required both nodes to use an identical `common_name` in their certificates. Starting in SSR 7.2.0, you can use a [SAN URI](#peering-identity-via-subject-alternative-name-uri-ssr-720) to carry the peering identity, allowing each node to have a unique CN — for example, `combo-east-node1` and `combo-east-node2` — while both certificates include the same `urn:ssr:peering:east-alias` SAN URI. +Because both HA nodes share the same `peering-common-name`, earlier releases required both nodes to use an identical `common_name` in their certificates. Starting in SSR 7.2.0, you can use a [SAN URI](#peering-identity-via-subject-alternative-name-uri) to carry the peering identity, allowing each node to have a unique CN — for example, `combo-east-node1` and `combo-east-node2` — while both certificates include the same `urn:ssr:peering:east-alias` SAN URI. ::: When two nodes are configured as a redundant pair, the keys are exchanged between nodes. This avoids rekeying on flow migration due to node failures. Keys can be safely exchanged between nodes as the HA sync interfaces are connected point to point over an SSH connection.