POST-QUANTUM CRYPTOGRAPHY FABRIC USER GUIDE
General user guide for deploying and using the PQC Fabric Deployment Tool
STRATISYSTEM OS — PQC FABRIC OPERATOR & ADMINISTRATOR GUIDE
SteelDome Technologies · StratiSYSTEM OS
Operator procedures for appliance readiness, secure peer enrollment, WireGuard tunnels, post-quantum key establishment, FRRouting/BGP, policy-based routing, topology, authenticated management, monitoring, key rotation and recovery.
This guide assumes PQC Fabric is available within StratiSYSTEM OS and focuses on deployment configuration and day-to-day administration.
OPERATOR CONVENTIONS
Commands are intended for a root shell unless noted. Router A uses example underlay address 192.168.59.201 and tunnel 10.250.0.1/32; Router B uses 192.168.59.202 and 10.250.0.2/32. Replace all example addresses, names, networks, fingerprints and prefixes with site-approved values.
Security: Do not disclose WireGuard private keys or preshared keys, cryptographic seeds, fabric or management private keys, or rotation journals. Verify peer identities through an independent trusted channel and retain access-controlled backups.
1. PRODUCT OVERVIEW AND OPERATING MODEL
StratiSYSTEM PQC Fabric provides distributed, node-managed encrypted network connectivity between approved appliances. WireGuard carries protected traffic, while authenticated enrollment and coordinated post-quantum key establishment maintain per-link preshared keys. FRRouting (FRR) exchanges approved IPv4 reachability through BGP, and Linux policy rules and dedicated routing tables implement site-specific policy-based routing (PBR).
FEATURE INVENTORY
| Capability | Available operation |
|---|---|
| Ready-only appliance initialization | Initialize an unconfigured appliance; tunnel assignment and peer activation remain separate operator actions. |
| Operator tunnel assignment | Set a unique local tunnel IPv4 /32 later; activation waits for enrollment. |
| Secure enrollment | SSH-assisted single-command join; TOFU, strict known_hosts or pinned SSH fingerprint; reciprocal SSH host trust. |
| Offline enrollment | Public manifests, signed ML-KEM offers, explicit certificate fingerprints and offer acceptance. |
| WireGuard peer permissions | Per-link AllowedIPs authorization, overlap rejection, persistent peer/host-route reconciliation. |
| Key rotation | ML-KEM-enabled hybrid TLS 1.3 control plane; per-link five-minute default schedule; durable journal and recovery. |
| Routing | Per-node FRR IPv4 BGP, exact prefix import/export lists, PBR rules and restricted transit. |
| Topology | Local peer inventory and handshake/BGP observations; JSON CLI/API. |
| Management | Local root CLI, authenticated HTTPS JSON API, role-based certificate authorization. |
| Persistence | Managed services retain WireGuard, identity and routing state across restarts; VM high availability remains a separate platform responsibility. |
| Platform-specific firewall policy | BaseOS only: managed default-deny TCP 9090 administration; on StratiSTOR/StratiSERV the existing firewall is untouched. |
| Peer-derived port authorization | BaseOS only: dynamically reconciles exact peer underlay addresses for UDP 51820/TCP 9443. External firewalls require their own permits. |
| Time-limited SSH enrollment | BaseOS only: scoped TCP 22 lease. On StratiSTOR/StratiSERV, temporary access must be authorized by the OS firewall owner. |
| Authenticated SSH session reuse | Enrollment and cleanup use a controlled SSH session; absent or expired temporary SSH leases are handled safely. |
| Local policy administration | Local AllowedIPs, BGP import/export and PBR edits require no SSH lease; remote coordinated join does. |
| External firewall ownership | Never writes nftables on StratiSTOR or StratiSERV, even when BaseOS directory coexists. |
| Native PKI tooling | Issue and manage approved CA, gateway, API and role-based client certificates using the supplied administration CLI. |
TRAFFIC AND CONTROL-PLANE SEPARATION
DISTRIBUTED FABRIC — DATA AND CONTROL PLANES
| ROUTER A | SECURE CHANNEL | ROUTER B |
|---|---|---|
| Underlay: 192.168.59.201 WireGuard: 10.250.0.1/32 |
WIREGUARD DATA ↔ UDP 51820 ↔ |
Underlay: 192.168.59.202 WireGuard: 10.250.0.2/32 |
| Local AllowedIPs and site policy | PQC CONTROL ↔ TCP 9443 ↔ |
Local AllowedIPs and site policy |
| Local FRR/BGP and PBR | BGP ROUTING ↔ TCP 179 over wg0 ↔ |
Local FRR/BGP and PBR |
| Management: TCP 9090 (approved sources) | SSH TCP 22: time-limited enrollment HTTPS API 8443: loopback by default |
Management: TCP 9090 (approved sources) |
BaseOS can manage default-deny ingress. StratiSTOR and StratiSERV retain their own host firewall ownership; the underlay and management ports require authorization through that host firewall.
Figure 1. Per-router local management with protected WireGuard data, PQC control, and BGP channels.
PQC Fabric is operated locally on each appliance rather than from a centralized mesh controller. It does not provide VM high availability, automatically authorize peers, plan a global mesh, or establish unrestricted transit. BGP exchanges approved reachability information; it does not distribute peer trust or router configuration files.
2. DEPLOYMENT PREREQUISITES AND PLANNING
HOST AND NETWORK READINESS
PQC Fabric management and services are supplied with StratiSYSTEM OS. Before creating a tunnel, confirm the appliance has working management networking, valid time synchronization, administrative access and the required product services.
On BaseOS, confirm the approved management access policy before enabling the PQC-managed default-deny firewall. On StratiSTOR or StratiSERV, coordinate all firewall changes with the host operating-system administrator.
| Readiness item | Operator verification |
|---|---|
| Management access | Confirm management interface, address, routes and access to the approved administration listener. |
| System time | Verify clock synchronization on both appliances; certificate validation depends on correct time. |
| PQC services | Confirm the installed services are available; run appliance status and host check. |
| Network policy | Permit approved administration, enrollment, tunnel and control traffic as appropriate to the StratiSYSTEM product. |
| Peer identity | Record approved remote underlay addresses, SSH host fingerprints and certificate fingerprints. |
ip -br address
ip route
chronyc tracking
stratisystem-pqcctl --local appliance status
stratisystem-pqcctl --local host check
systemctl is-active stratisystem-pqc-agent stratisystem-pqc-api
PLAN THESE INPUTS
Unique VM hostname, management underlay address and management network interface per appliance.
Different WireGuard tunnel IPv4 /32 addresses; never duplicate identities when cloning a VM.
BaseOS: approved administrator CIDRs and automatically derived enrolled peer underlay permits. StratiSTOR/StratiSERV: coordinate equivalent allowances with the host firewall administrator.
Approved SSH trust method and per-router certificate fingerprint verification.
Authorized site prefixes on both WireGuard peers and their corresponding FRR import/export lists.
Per-node BGP ASN/router ID, permitted neighbor tunnel IPs, and any PBR table/priority selection.
SERVICE PORTS AND FIREWALL PLANNING
| Transport | Port | Use | Security scope |
|---|---|---|---|
| TCP | 9090 | Administrative UI / terminal | BaseOS: approved admin CIDRs. Elsewhere: host OS firewall. |
| UDP | 51820 | WireGuard encrypted tunnel | BaseOS: enrolled peer underlay /32 only. Elsewhere: host OS firewall. |
| TCP | 9443 | Fabric control / coordinated rotation | BaseOS: enrolled peer underlay /32 only. Elsewhere: host OS firewall. |
| TCP | 179 | FRR BGP | BaseOS: on wg0, configured BGP peers. Elsewhere: host OS firewall. |
| TCP | 22 | SSH first enrollment / coordinated remote join | BaseOS: temporary enrollment source /32. Elsewhere: host OS firewall. |
| TCP | 8443 | Mutual-TLS JSON API | Local mTLS API; default loopback endpoint. |
| Other | — | All unsolicited inbound | BaseOS: default DROP. Other products: host firewall owns ingress. |
3. PREPARE AND INITIALIZE THE APPLIANCE
An installed StratiSYSTEM appliance can remain in a ready-only state until tunnel addressing and peer authorization are approved. No WireGuard tunnel or BGP site routing is activated merely by checking readiness. BaseOS may enforce PQC-managed default-deny ingress; StratiSTOR and StratiSERV retain their host firewall ownership.
OPERATOR-ACTIVATED FABRIC LIFECYCLE
| 01 — APPLIANCE READY | 02 — TUNNEL ASSIGNED | 03 — PEERS ENROLLED | 04 — ROUTING ENABLED |
|---|---|---|---|
| PQC services available StratiSYSTEM platform validated Ready-only state |
Assign unique tunnel /32 Persist configuration No peer yet |
Verify signed peer trust Derive key material Activate WireGuard |
Configure local BGP policy Apply FRR/PBR Verify protected routing |
Figure 2. Ready-only provisioning, delayed tunnel assignment, peer enrollment and optional local routing activation.
INITIAL APPLIANCE READINESS AND PROVISIONING
Perform these checks on Router A and Router B after management networking is configured. If the StratiSYSTEM provisioning workflow has already initialized PQC Fabric, do not repeat first-boot provisioning. Continue with readiness verification and tunnel assignment.
If PQC Fabric has not yet been initialized on an appliance, use the provided appliance provision operation. It prepares protected local identity, service configuration and initial ready-only state without joining a peer. Review approved management and firewall access before making provisioning changes.
# Check the already-installed appliance
stratisystem-pqcctl --local appliance status
stratisystem-pqcctl --local host check
# Only for an appliance that has not yet been provisioned:
stratisystem-pqcctl --local --bin-dir /usr/sbin appliance provision
# Confirm the ready-only state before any peer enrollment
stratisystem-pqcctl --local fabric tunnel status
stratisystem-pqcctl --local fabric status
EXPECTED READY-ONLY STATE
| Item | Expected ready-only state |
|---|---|
| PQC management services | Available and initialized for local administration. |
| Fabric identity and management PKI | Existing appliance identity and certificates present and protected. |
| WireGuard router keys | Local WireGuard identity generated and preserved. |
| wg0 configuration and interface | Absent until tunnel address and peer enrollment are completed. |
| Routing policy | Local configuration present; BGP/site routing disabled until explicitly enabled. |
| Rotation | Enabled by default for initialized nodes, with no active per-link workers until peers are enrolled. |
| Firewall | BaseOS: approved default-deny policy; StratiSTOR/StratiSERV: policies controlled by the respective host firewall. |
VERIFY READY-ONLY STATE
stratisystem-pqcctl --local fabric tunnel status
stratisystem-pqcctl --local host check
stratisystem-pqcctl --local fabric status
stratisystem-pqcctl --local fabric topology
systemctl is-enabled stratisystem-pqc-agent stratisystem-pqc-api
# Expected key fields
{
"state": "ready_unconfigured",
"configuration_present": false,
"interface": "wg0",
"tunnel_address": ""
}
| IMPORTANT | “Ready” does not mean tunnel-active. fabric tunnel status reports whether an address/configuration exists; use wg show wg0 and ip -br address show wg0 to verify live activation after enrollment. |
|---|
4. ASSIGNING TUNNEL ADDRESSES LATER
The operator can keep the appliances in ready-only mode until connectivity is approved. Assign a unique IPv4 /32 locally on each router. This is deliberately a separate lifecycle action from joining peers.
ROUTER A
stratisystem-pqcctl --local \
--tunnel-address 10.250.0.1/32 \
fabric tunnel set
stratisystem-pqcctl --local fabric tunnel status
ROUTER B
stratisystem-pqcctl --local \
--tunnel-address 10.250.0.2/32 \
fabric tunnel set
stratisystem-pqcctl --local fabric tunnel status
The command updates host.json and creates the protected WireGuard configuration; interface activation is deferred until fabric join. Reapplying the same address is idempotent. Attempts to replace an already assigned address or take over an unexpected live wg0 interface are refused.
| DO NOT | Do not enable wg-quick@wg0 merely to transition from ready-only to configured. Use the supported enrollment flow, which provisions the verified peer and activates the link. |
|---|
5. SSH-ASSISTED FABRIC ENROLLMENT
AUTHORIZE TEMPORARY SSH ON THE DESTINATION
IMPORTANT — StratiSTOR/StratiSERV: fabric enrollment-open intentionally refuses to modify the firewall. The host firewall administrator must temporarily allow TCP 22 from Router A to Router B, as well as the required router underlay ports. After enrollment, remove that temporary host-level SSH exception using the same host firewall manager.
On BaseOS, TCP 22 is denied by the PQC-managed firewall until a narrowly scoped enrollment lease is opened on the destination router. On StratiSTOR/StratiSERV, this CLI cannot open host firewall rules: obtain a temporary TCP 22 permit from the OS firewall owner instead. Use console or existing approved administration to prepare Router B.
# BASEOS ONLY: Router B — temporarily allow SSH from A
# Router B (target): temporarily permit A to enroll
stratisystem-pqcctl --local \
--enrollment-source 192.168.59.201 \
--enrollment-minutes 10 \
fabric enrollment-open
stratisystem-pqcctl --local fabric enrollment-status
Then initiate fabric join from Router A. Both systems exchange signed identities, verify the WireGuard tunnel and coordinate rotation. BaseOS dynamically reconciles peer firewall permits; StratiSTOR/StratiSERV leave host firewall controls unchanged. Enrollment retains SSH session and safely handles an absent or expired temporary lease.
TWO-ROUTER QUICK JOIN: TUNNEL ONLY
After setting both tunnel addresses, run the following from Router A. It authorizes the opposite tunnel /32, exchanges signed manifests, generates the ML-KEM-derived PSK, configures both peers, activates WireGuard and verifies the tunnel.
stratisystem-pqcctl --local \
--ssh root@192.168.59.202 \
--link-id site-a-b \
fabric join
TWO-ROUTER JOIN WITH PERMITTED PROTECTED-SITE NETWORKS
Use this variant if the pair will carry the validated test prefixes or customer networks. These authorizations must be reciprocal. An absent prefix cannot be accepted by FRR routing validation even if BGP is configured.
stratisystem-pqcctl --local \
--ssh root@192.168.59.202 \
--link-id site-a-b \
--allowed-ips 10.20.20.1/32 \
--remote-allowed-ips 10.10.10.1/32 \
fabric join
SSH TRUST CONTROLS
| Flag | Behavior |
|---|---|
| --ssh root@HOST | Explicit enrollment target; no automated subnet scan. |
| --ssh-strict | Require preapproved host key in known_hosts. |
| --ssh-host-key-sha256 SHA256:PIN | Require exact approved Ed25519 SSH host-key fingerprint. |
| --reciprocal-ssh-trust=false | Disable reverse signed host-key pinning. |
| --ssh-port / --ssh-identity | Select nondefault port or SSH identity. |
| --allow-advertised-endpoint | Explicit NAT override when signed underlay differs from SSH target. |
| --verify-tunnel=false | Skip post-join ICMP check only when operationally necessary. |
| SECURITY | First-contact TOFU is the default for an explicit join and protects against later host-key changes, not an attacker on the initial contact. Prefer preapproved fingerprints/strict trust outside a controlled lab. |
| --- | --- |
VERIFY LINK ESTABLISHMENT
# Router A
wg show wg0
wg show wg0 allowed-ips
ping -c 5 -I wg0 10.250.0.2
stratisystem-pqcctl --local fabric status
# Router B
wg show wg0
ping -c 5 -I wg0 10.250.0.1
After a successful first join, wg-quick@wg0 is enabled for subsequent restarts. The coordinator is the initiating router for this link; the other router is its follower for coordinated rotation.
6. MANUAL AND OFFLINE ENROLLMENT
Where interactive SSH enrollment is unsuitable, operators can exchange public-only signed manifests and encrypted offers. The peer certificate fingerprint must be validated through an independent trusted channel before authorization.
STEP-BY-STEP PUBLIC-MANIFEST EXCHANGE
# On Router B: public export
stratisystem-pqcctl --local \
--out /root/router-b.public.json fabric export
# On Router A: create signed offer after verified transfer
stratisystem-pqcctl --local \
--peer /root/router-b.public.json \
--fingerprint '<B_CERT_SHA256>' \
--link-id site-a-b \
--out /root/site-a-b.offer.json fabric offer
# On Router B: accept the offer after verified transfer
stratisystem-pqcctl --local \
--peer /root/site-a-b.offer.json \
--fingerprint '<A_CERT_SHA256>' \
fabric accept
For manual workflows, explicitly review whether and when activation occurs. The available fabric activate command performs the local privileged activation/reconciliation after durable enrollment changes. Public manifests do not include WireGuard, TLS or ML-KEM private keys or PSKs.
OTHER CONTROLLED LINK OPERATIONS
stratisystem-pqcctl --local fabric status
stratisystem-pqcctl --local fabric sync-routes
stratisystem-pqcctl --local fabric activate
stratisystem-pqcctl --local --link-id site-a-b fabric remove
Before removing an active rotating link, disable rotation on both endpoints, check that an in-flight rotation has completed, and coordinate deletion at each side. Removing a link does not automatically revoke a previously trusted certificate.
7. MANAGING WIREGUARD ALLOWEDIPS AND HOST ROUTES
WireGuard AllowedIPs is a cryptographic traffic-selection authorization, not simply a Linux routing instruction. Managed WireGuard configuration uses Table = off: wg-quick does not automatically install every remote site prefix as a main-table route. The fabric instead pins the tunnel-neighbor /32 route and leaves customer/site routing to FRR and explicit PBR.
ADD/REPLACE APPROVED ADDITIONAL REMOTE PREFIXES
# Router A: authorize Router B's test endpoint
stratisystem-pqcctl --local --link-id site-a-b \
--allowed-ips 10.20.20.1/32 fabric authorize
# Router B: authorize Router A's test endpoint
stratisystem-pqcctl --local --link-id site-a-b \
--allowed-ips 10.10.10.1/32 fabric authorize
wg show wg0 allowed-ips
This operation replaces the additional site-prefix list for the selected link, while always retaining the peer tunnel /32. It updates persistent and live configuration without replacing the existing PSK. Repeated SSH join with explicit AllowedIPs flags can reconcile both ends instead.
CONSTRAINTS AND CAUTIONS
Reject duplicate, overlapping, malformed or default-route (0.0.0.0/0) authorizations.
Never assign the same or overlapping site prefix to multiple peers on a shared multipoint wg0 interface.
BGP import/export authorization does not automatically expand WireGuard AllowedIPs.
The tunnel peer /32 remains a separate pinned route; use fabric sync-routes for restoration and diagnosis.
For a production route-withdrawal/failover design, test that PBR does not leave unwanted traffic paths after a BGP route disappears.
8. FRROUTING: BGP CONFIGURATION AND ROUTE POLICY
PQC Fabric integrates FRR with local IPv4 unicast BGP and node-local PBR. The routing reconciler stages only declared BGP configuration and protects unrelated FRR settings. BGP is initially disabled and has no site advertisements in the basic examples. On BaseOS only, BGP-related nftables permissions are reconciled; StratiSTOR/StratiSERV retain host firewall ownership.
BASIC BGP ADJACENCY: NO CUSTOMER PREFIXES
# Create operator-approved routing JSON at these paths before applying.
# Router A
stratisystem-pqcctl --local \
--data /root/routing-router-a.json routing set
stratisystem-pqcctl --local routing apply
# Router B
stratisystem-pqcctl --local \
--data /root/routing-router-b.json routing set
stratisystem-pqcctl --local routing apply
# Verify on both
vtysh -c 'show bgp ipv4 unicast summary'
stratisystem-pqcctl --local routing status
stratisystem-pqcctl --local fabric topology
The basic examples use ASN 65001 on A and 65002 on B; they intentionally advertise/accept zero site prefixes. They validate that the BGP adjacency can be established through WireGuard without allowing customer traffic.
BGP PREFIX SECURITY MODEL
Only explicitly declared neighbors are configured; per-neighbor import/export lists are exact-prefix policy.
Exported prefixes must also appear in the local advertise list.
The local prefix must exist in the router RIB for a BGP network statement to originate it.
The remote site prefix must be covered by the matching WireGuard AllowedIPs peer.
BGP TCP/179 is authorized for configured neighbors on wg0 only while routing is enabled; it is never open on the underlay management interface.
The system rejects a default-route advertisement or default-route PBR policy.
9. SITE-ROUTING AND POLICY-BASED ROUTING LAB
This optional lab uses JSON from the provided deployment examples and temporary dummy site interfaces; they are not created automatically on an appliance. Copy example JSON to an operator-managed path or pass JSON with --data - on standard input. The dummy interfaces must be recreated after a reboot.
CREATE THE LOCAL SITE ENDPOINTS
# Router A
ip link show sdtest0 >/dev/null 2>&1 || \
ip link add sdtest0 type dummy
ip address show sdtest0 | grep -q '10.10.10.1/32' || \
ip addr add 10.10.10.1/32 dev sdtest0
ip link set sdtest0 up
# Router B
ip link show sdtest0 >/dev/null 2>&1 || \
ip link add sdtest0 type dummy
ip address show sdtest0 | grep -q '10.20.20.1/32' || \
ip addr add 10.20.20.1/32 dev sdtest0
ip link set sdtest0 up
JOIN WITH SITE-PREFIX AUTHORIZATIONS
# Router A, after both tunnel addresses have been assigned
stratisystem-pqcctl --local \
--ssh root@192.168.59.202 --link-id site-a-b \
--allowed-ips 10.20.20.1/32 \
--remote-allowed-ips 10.10.10.1/32 fabric join
If the tunnel was already joined without these prefixes, use fabric authorize independently on each router (Section 7) or repeat the verified SSH join with the explicit flags.
APPLY PREBUILT FRR/PBR CONFIGURATIONS
# Create operator-approved routing JSON at these paths before applying.
# Router A
stratisystem-pqcctl --local \
--data /root/site-test-router-a.json routing set
stratisystem-pqcctl --local routing apply
# Router B
stratisystem-pqcctl --local \
--data /root/site-test-router-b.json routing set
stratisystem-pqcctl --local routing apply
VERIFY BOTH DIRECTION PATHS
# Both routers
vtysh -c 'show bgp ipv4 unicast summary'
ip -4 rule show
ip -4 route show table 2001
wg show wg0 allowed-ips
# Router A
ip route get 10.20.20.1 from 10.10.10.1
ping -c 10 -I 10.10.10.1 10.20.20.1
# Router B
ip route get 10.10.10.1 from 10.20.20.1
ping -c 10 -I 10.20.20.1 10.10.10.1
Expected: BGP Established and one site prefix sent/received on each router; policy priority 20001 and table 2001 via wg0; successful sourced pings. With these examples, the PBR route in table 2001 is explicitly pinned to the remote tunnel IP. It is not automatically withdrawn in lockstep with the BGP route.
| SCOPE | This tests locally generated, source-addressed traffic. Real LAN-to-LAN transit additionally needs attached LANs, explicit ingress interface declarations, correct return paths and allowed nftables forwarding policy. |
|---|
10. TOPOLOGY VISIBILITY AND MULTI-PEER DESIGN
TOPOLOGY COMMANDS
stratisystem-pqcctl --local fabric topology
stratisystem-pqcctl --local fabric topologies
stratisystem-pqcctl --local routing status
wg show wg0
vtysh -c 'show bgp ipv4 unicast summary'
Local topology JSON includes node name, peer ID/name, coordinator/follower role, interface, peer public key, endpoint, AllowedIPs, last-handshake timestamp, live activity classification, configured BGP neighbors and FRR summary, plus managed PBR count. The topology field identifies isolated, single-link or multi-peer local connectivity. Observation is local rather than a guaranteed network-wide topology graph.
TOPOLOGY SCALING AND LIMITS
| Topology | Supported operational model |
|---|---|
| One-to-many / many-to-one | Multiple distinct peer relationships and local BGP neighbors; each requires explicit enrollment and nonoverlapping cryptokey routes. |
| Partial mesh / many-to-many | Multiple explicitly enrolled links; local visibility only, without centralized global mesh classification. |
| High availability | VM/hypervisor-owned in this deployment; no built-in multi-controller route/PSK failover. |
| Large-scale fabrics | Config schema bounds up to 10,000 peer relationships, not a certified load/performance capacity; avoid indiscriminate full mesh. |
11. AUTOMATIC KEY ROTATION AND JOURNALED RECOVERY
COORDINATED POST-QUANTUM KEY ROTATION
| 01 — CONTROL | 02 — PREPARE | 03 — COMMIT | 04 — RECONCILE |
|---|---|---|---|
| Authenticated hybrid TLS 1.3 TCP 9443 |
Derive replacement PSK Journal intent |
Update reciprocal WireGuard PSKs sequentially |
Persist committed generation Recover from incomplete work |
Default interval: five minutes per enrolled link. Rotation is journaled, but sequential key replacement can cause brief packet loss and is not a zero-loss guarantee.
Figure 3. Authenticated coordinated rotation with durable generation journals and reconciliation.
Rotation is enabled by default on newly initialized nodes. Each enrolled link gets a coordinator and follower. The control plane uses mutually authenticated TLS 1.3 restricted to X25519MLKEM768; per-generation material updates the WireGuard preshared-key slot. This is additive PQC key establishment, not a replacement for WireGuard encryption.
ROTATION COMMANDS
stratisystem-pqcctl --local fabric rotation-status
stratisystem-pqcctl --local fabric rotation-enable
stratisystem-pqcctl --local fabric rotation-disable
# Coordinator side: queue an immediate rotation
stratisystem-pqcctl --local fabric rotate site-a-b
Defaults: 5-minute interval for each enrolled link; allowed rotation_interval in agent.json is 1 minute to 24 hours, and timeout 5 seconds to 2 minutes. The coordinator schedules staggered attempts and bounded retries; a rotate request only queues work, so inspect the committed generation afterward.
HOW TO INTERPRET ROTATION-STATUS
| Field | Meaning |
|---|---|
| enabled | Whether automatic rotation is enabled on the node. |
| id / peer / role | Link identifier, peer identity and coordinator/follower role. |
| generation | Last durably committed shared PSK generation (0 at enrollment). |
| phase | stable on successful reconciliation; intermediate phases may appear briefly. |
| committed_at | Timestamp of the last committed generation, not a scheduler heartbeat. |
| interval | Per-link automatic rotation interval. |
ROTATE WHILE TESTING TRAFFIC
# Router A, first terminal: continuous source-addressed ping
ping -n -i 0.2 -I 10.10.10.1 10.20.20.1
# Router A, second terminal: trigger rotation
stratisystem-pqcctl --local fabric rotate site-a-b
stratisystem-pqcctl --local fabric rotation-status
# Router B
stratisystem-pqcctl --local fabric rotation-status
journalctl -u stratisystem-pqc-agent --since '-10 min' --no-pager
| LIMITATION | Kernel WireGuard has only one active PSK per peer. Two sides switch sequentially, so brief packet loss is possible. The journal enables recovery/reconciliation but is not a guarantee of zero-loss rekey or instant recovery after arbitrary crash injection. |
|---|
ROTATION INTERNALS AND SECRETS
Per-link root-only journals live under /var/lib/stratisystem/pqc/rotations. They record committed and in-progress recovery states and can contain secret PSK material. The persistent WireGuard configuration stores the currently committed PSK. Never attach rotation journal JSON to routine diagnostic bundles.
12. CLI COMMAND REFERENCE
Use --local for node-side operations. Mutating commands typically require root. Remote commands use --api https://HOST:8443 with --ca, --cert and --key for management mutual TLS. Unless a command says otherwise, CLI responses are JSON.
| Command family | Subcommand / operation | Purpose |
|---|---|---|
| host | init / check / prepare / firewall | Discover and enforce host policy; read compliance. |
| fabric | init / tunnel status / tunnel set | Initialize identity; show ready/configured state; assign tunnel /32. |
| fabric | join / export / offer / accept | Automatic SSH or offline signed-manifest enrollment. |
| fabric | status / topology / topologies | Local fabric inventory and topology observation. |
| fabric | authorize / sync-routes / activate | Update AllowedIPs; restore peer host routes; activate saved intents. |
| fabric | remove / trust-ssh | Controlled teardown; signed reverse SSH-host binding. |
| fabric | rotation-status / rotation-enable / rotation-disable / rotate ID | Monitor and control automatic PSK rotation. |
| routing | init / get / set / apply / status | Prepare, stage, reconcile and inspect FRR/PBR configuration. |
| wg | interfaces / interface IFACE / peer set / peer remove | Inspect kernel WG state or manipulate desired peer records. |
| config | get / set | Management agent desired config (remote ETag-guarded update). |
| appliance | provision / status | Initialize an unconfigured appliance and inspect installed service/readiness state. |
| pki | init / gateway / api / client / pair | Certificate and client identity administration (optional). |
COMMON CLI FLAGS
| Option | Use |
|---|---|
| --local | Operations against local host/agent and privileged local files. |
| --host-config PATH | Select a host policy file; default /etc/stratisystem/pqc/host.json. |
| --routing-config PATH | Override routing policy location; default /etc/stratisystem/pqc/routing.json. |
| --tunnel-address IP/32 | Local tunnel assignment in host init/fabric tunnel set. |
| --ssh USER@IP, --link-id ID | Automatic enrollment target and stable link identifier. |
| --allowed-ips CIDR[,CIDR] | Authorize additional remote site prefixes for this local link. |
| --remote-allowed-ips CIDR[,CIDR] | Authorize prefixes back toward this node on remote peer. |
| --out PATH / --peer PATH / --fingerprint SHA256 | Public manifest and signed offline offer workflows. |
| --data FILE|- / --if-match ETAG | JSON staged configuration and concurrent update guard. |
| --api, --ca, --cert, --key | Management API URI and mTLS credentials. |
| --rotation-enabled=true|false | Initial rotation configuration on a newly provisioned appliance; normally enabled. |
| --admin-cidrs IP/CIDR | Permitted TCP 9090 sources in BaseOS-managed policy; other OSs retain own firewall policies. |
13. JSON CONFIGURATION REFERENCE
current keeps four declarative configuration categories plus state and secrets. Use the CLI to initialize or stage validated JSON whenever possible; do not change actively managed files without backup, validation and service coordination.
| File | Purpose and ownership |
|---|---|
| /etc/stratisystem/pqc/host.json | Management interface, tunnel /32 (optional in ready-only), sysctl/firewall policy. |
| /etc/stratisystem/pqc/agent.json | Node identity/control listener, rotation toggle, per-link peer settings. |
| /etc/stratisystem/pqc/api.json | Management TLS listener, cert/key/CA, local agent socket and concurrency. |
| /etc/stratisystem/pqc/routing.json | Enabled flag, ASN, BGP neighbors, exact import/export and PBR policies. |
| /etc/wireguard/wg0.conf | Persistent wg-quick local/interface/peer config; Table=off for new project-managed interfaces. |
| /etc/frr/frr.conf | Project-marked BGP output; protected against overwriting an operator-owned FRR config. |
| /var/lib/stratisystem/pqc/ | Pinned enrollment state, desired policy, routing-applied state and root-only rotation journals. |
LOCAL IDENTITIES, CERTIFICATES AND SENSITIVE MATERIAL
| Path | Function / handling |
|---|---|
| /etc/wireguard/router.key, router.pub | Unique WireGuard private/public node identity; never clone the private key. |
| /etc/stratisystem/pqc/fabric.crt, fabric.key | Unique fabric Ed25519 authentication certificate and private key. |
| /etc/stratisystem/pqc/fabric-ca.crt | Trusted fabric certificates / approved peer trust bundle. |
| /etc/stratisystem/pqc/kem768.seed | Node-local ML-KEM-768 private seed; secret, never export. |
| /etc/stratisystem/pqc/management-ca.crt, management-ca.key | Lab-local management certificate authority; external issuance recommended for production. |
| /etc/stratisystem/pqc/api.crt, api.key | Management HTTPS API server identity. |
| /etc/stratisystem/pqc/local-admin.crt, local-admin.key | Lab bootstrap pqc-admin client certificate; never share private key across routers. |
| /var/lib/stratisystem/pqc/trusted/ | Approved peer binding and trust records. |
HOST POLICY FIELDS
| JSON field | Meaning / rule |
|---|---|
| version | Must be 1. |
| management_interface | Management NIC: discovered on native first boot or overridden by --management-interface. |
| wireguard_interface | Defaults to wg0. |
| tunnel_address | Optional during ready-only; assign unique IPv4 /32 before join. |
| disable_ipv6_forwarding | Host IPv6 forwarding policy. |
| ntp_wait_seconds | NTP readiness wait, default 45 s; allowed 1–120. |
| firewall.mode | BaseOS only: managed/adopt for the PQC-owned nftables table. StratiSTOR/StratiSERV never modify firewall state, irrespective of this JSON field. |
| firewall.admin_cidrs / fabric_cidrs | BaseOS: admin_cidrs allows TCP 9090 and peer endpoint permits derive from enrolled identities. External host firewall controls apply on StratiSTOR/StratiSERV. |
| firewall.protected_cidrs / lan_interface | Traffic-forwarding scope; nftables forwarding permit management runs only on BaseOS. Host OS networking policies remain authoritative elsewhere. |
| firewall.allow_wg_transit | Explicitly managed transit setting; default-deny otherwise. |
| firewall.*_port | Defaults: Cockpit/admin TCP 9090, SSH TCP 22 (lease only), management API TCP 8443 (loopback), agent TCP 9443, WG UDP 51820, BGP TCP 179 on wg0 only. |
ROUTING JSON SCHEMA
{
"version": 1,
"enabled": true,
"wg_interface": "wg0",
"local_tunnel": "10.250.0.1",
"asn": 65001,
"router_id": "10.250.0.1",
"advertise": ["10.10.10.1/32"],
"neighbors": [{
"address": "10.250.0.2", "asn": 65002,
"import": ["10.20.20.1/32"],
"export": ["10.10.10.1/32"]
}],
"policies": [{
"id": "site-a-to-b", "source": "10.10.10.1/32",
"destination": "10.20.20.1/32",
"table": 2001, "priority": 20001,
"next_hop": "10.250.0.2"
}]
}
An optional ingress field on each policy authorizes forwarding from a named ingress NIC; leave it absent for locally originated dummy-host tests. The configuration rejects default routes and enforces exclusive rule priorities 20000–20999 and tables 2000–2999. Neighbor and prefix limits are validated by the schema.
AGENT AND API FILES
agent.json contains node_name, listen, CA/cert/key paths, agent_socket, rotation_enabled, max_concurrent_rotations, max_inbound_sessions and peers[]. Peers include id, role, peer_name, remote control endpoint (for coordinator), tunnel_id, interface, reciprocal WG public keys and optional per-link rotation_interval/timeout. api.json provides listen, cert_file, key_file, client_ca_file, agent_socket and max_concurrent_requests.
14. HTTPS JSON API AND ACCESS CONTROL
The dedicated HTTPS management API is configured for local-only access (127.0.0.1:8443) by default. External TCP 9090 management is a separate OS-supplied administrative listener; PQC Fabric does not install it. On StratiSTOR/StratiSERV the host OS firewall controls reachability for both.
The API daemon is a restricted proxy to a root-controlled Unix-socket agent; it never directly invokes WireGuard or holds WireGuard secrets. TLS 1.3 mutual authentication uses the configured management PKI and an X25519MLKEM768 key exchange. User roles are derived from certificate OrganizationalUnit values, not caller-supplied headers.
ACCESS ROLES
| Certificate OU | Authorized actions |
|---|---|
| pqc-viewer | Read-only health, links, host, WireGuard, topology, routing and rotation status. |
| pqc-operator | Viewer plus POST rotation request. |
| pqc-admin | Operator plus staged config changes, rotation toggles and enrollment/peer changes. |
API ENDPOINT INDEX
| Method | Path | Minimum role / note |
|---|---|---|
| GET | /v1/health, /v1/status | Viewer; health and agent peer counters |
| GET | /v1/host/compliance, /v1/host/policy | Viewer; host assurance and desired policy |
| GET | /v1/fabric/capabilities, /v1/fabric/enrollment | Viewer; supported capability and public manifest |
| GET | /v1/fabric/links, /v1/fabric/topology | Viewer; redacted links and observed adjacency |
| POST | /v1/fabric/offers, /v1/fabric/accept, /v1/fabric/remove | Admin; stage signed enrollment and remove intent |
| GET | /v1/rotations/status | Viewer; durable generation and phase |
| PUT | /v1/rotations/config | Admin; enabled boolean |
| POST | /v1/rotations/{id} | Operator; queue rotation |
| GET | /v1/routing/status, /v1/routing/config | Viewer; FRR/PBR status or staged policy |
| PUT | /v1/routing/config | Admin; requires If-Match, only stages |
| GET/PUT | /v1/config | Viewer/Admin; desired agent config, If-Match on PUT |
| GET | /v1/wireguard/interfaces, /v1/wireguard/interfaces/{iface} | Viewer; redacted live interface view |
| GET | /v1/wireguard/desired-peers | Viewer; desired peer inventory |
| PUT/DELETE | /v1/wireguard/peers | Admin; desired live peer changes |
REMOTE CLI EXAMPLE
stratisystem-pqcctl \
--api https://127.0.0.1:8443 \
--ca /etc/stratisystem/pqc/management-ca.crt \
--cert /etc/stratisystem/pqc/local-admin.crt \
--key /etc/stratisystem/pqc/local-admin.key \
fabric links
The local-admin certificate and CA shown here are first-boot lab defaults on the same appliance; do not distribute that private key across nodes or operators. For remote management, issue individual operator certificates from a controlled PKI. The CLI prints returned ETags to stderr; config PUT operations require a matching If-Match header.
15. SECURITY ARCHITECTURE AND OPERATIONAL BOUNDARIES
15.1 FIREWALL OWNERSHIP BY STRATISYSTEM PRODUCT
The firewall policy is intentionally product-aware. The StratiSTOR and StratiSERV environments may include the /baseos directory, but they always take precedence: PQC Fabric skips all nftables writes on these platforms.
| Operation / platform | BaseOS | StratiSTOR or StratiSERV |
|---|---|---|
| Initial provision / early boot | Creates/reconciles PQC-owned default-drop table | No PQC firewall modification |
| Join / remove signed peer | Adds/removes exact peer permits | No PQC firewall modification |
| Temporary SSH enrollment | Local CLI opens short lease; closes on expiry | CLI cannot open it; OS firewall owner must permit access |
| Routing apply / disable | Manages BGP and forward permits | FRR/PBR changes; nftables untouched |
| host check / service startup | Checks PQC-owned managed firewall | Reports externally managed; does not require PQC table |
| Both product and BaseOS paths | BaseOS policy only if no storage/compute product exists | Storage/compute product takes precedence |
Operational requirement: to establish peers on StratiSTOR/StratiSERV, pre-authorize UDP 51820 and TCP 9443 between router underlay endpoints in the OS firewall policy; permit TCP 179 through wg0 for BGP if needed. For SSH enrollment, separately authorize TCP 22 from the initiating router for a short period and revoke it afterward. TCP 9090 access is likewise controlled by the host firewall.
On BaseOS only, PQC Fabric owns inet stratisystem_pqc with default-drop inbound/forward chains. TCP 9090 is allowed for approved administrators, router underlay ports are peer-derived, and BGP accepts only declared neighbors on wg0. On StratiSTOR/StratiSERV there is no PQC-created firewall table or rule modification; the host product enforces network ingress policy.
PLATFORM-AWARE FIREWALL OWNERSHIP
| BASEOS-ONLY APPLIANCE | STRATISTOR / STRATISERV HOST |
|---|---|
| PQC Fabric owns its nftables table TCP 9090: approved administrators UDP 51820 and TCP 9443: enrolled peers TCP 22: temporary enrollment lease TCP 179: configured BGP on wg0 only Unsolicited inbound traffic: DROP |
Host firewall remains under its OS owner PQC Fabric does not add or edit nftables rules No automatic SSH exception Operator must permit required ports WireGuard, BGP and key rotation still operate Applies even when /baseos also exists |
Figure 4. Different network policy ownership on BaseOS and on StratiSTOR/StratiSERV.
BaseOS: fabric4 begins empty. Signed enrollment authorizes exact peer underlay /32s for UDP 51820/TCP 9443; final peer removal revokes them. StratiSTOR/StratiSERV: these events never create, flush, or delete nftables rules. The operator must ensure the existing platform firewall permits the necessary router traffic.
| Trigger / change | BaseOS-managed firewall outcome |
|---|---|
| Initial ready-only provisioning | BaseOS ONLY: Empty fabric4 and enrollment4; TCP 9090 admin CIDRs only. |
| fabric enrollment-open | BaseOS ONLY: Temporary TCP 22 accept from single enrollment4 IPv4 address (1–15 min). |
| Successful fabric join | BaseOS ONLY: Allow exact enrolled underlay /32 to UDP 51820 + TCP 9443; close lease. |
| fabric remove / final shared peer | BaseOS ONLY: Revoke peer underlay /32 from fabric4. |
| routing apply enabled | BaseOS ONLY: BGP TCP 179 only on wg0 from configured tunnel neighbors; explicit PBR forwarding. |
| Routing disabled / policy removed | BaseOS ONLY: Remove routing BGP/forwarding grants; other incoming flows still denied. |
| Reboot / host firewall reconciliation | BaseOS ONLY: Rebuild trusted peer set from agent state plus matching identity pins. |
15.2 INSPECT FIREWALL STATE (BASEOS ONLY)
On BaseOS, inspect the PQC-owned nftables sets using the commands below. On StratiSTOR/StratiSERV, do not assume this nftables table exists and do not apply ad hoc PQC nft rules; use the installed platform firewall-management and diagnostics procedures.
# BaseOS ONLY: inspect PQC-owned firewall
stratisystem-pqcctl --local host check
stratisystem-pqcctl --local fabric enrollment-status
nft -a list table inet stratisystem_pqc
nft list set inet stratisystem_pqc fabric4
nft list set inet stratisystem_pqc enrollment4
# On StratiSTOR/StratiSERV, use the platform firewall tools instead.
15.3 LOCAL ROUTING POLICY VERSUS REMOTE CONFIGURATION
LOCAL CONFIGURATION OWNERSHIP AND BGP EXCHANGE
| ROUTER A — LOCAL POLICY | EXCHANGE | ROUTER B — LOCAL POLICY |
|---|---|---|
| Remote AllowedIPs for Site B Own BGP ASN and import/export filters Own PBR and firewall policy |
BGP ↔ authorized route reachability ↔ No remote config push |
Remote AllowedIPs for Site A Own BGP ASN and import/export filters Own PBR and firewall policy |
Local AllowedIPs, BGP and PBR edits do not require a remote SSH lease. Changes involving remote enrollment require explicit authorization; BGP exchanges reachability, not WireGuard peer authorizations.
Figure 5. Per-node configuration ownership; BGP exchanges network reachability automatically.
An enrolled router can always be configured through its local root CLI without reopening SSH. Configure AllowedIPs and routing policies separately on both routers; BGP then exchanges allowed reachability. Running fabric join on Router A to modify Router B at the same time is a remote SSH operation and requires a temporary SSH exception on B.
| Operation | SSH lease on Router B? |
|---|---|
| A local: fabric authorize or routing set/apply | No |
| B local: fabric authorize or routing set/apply | No |
| BGP advertisements and route withdrawals | No |
| Coordinated rotation / peer control over TCP 9443 | No |
| A pushes reciprocal AllowedIPs via fabric join --ssh root@B | Yes: B must permit SSH via BaseOS lease or StratiSTOR/StratiSERV firewall administration. |
| Enroll a new router through SSH | Yes: destination firewall owner permits temporary SSH. |
15.4 SSH LEASE CLEANUP AND RECOVERY
Fabric enrollment reuses its authenticated SSH connection through join and enrollment cleanup. If a temporary enrollment lease is absent or expired, the cleanup treats it as closed only after confirming the firewall state. This removes harmless warnings without treating unreadable or missing firewall sets as success.
# On Router B — verify or idempotently close an expired lease
stratisystem-pqcctl --local fabric enrollment-status
stratisystem-pqcctl --local \
--enrollment-source 192.168.59.201 \
fabric enrollment-close
# Expected when already absent: ok=true, already_closed=true
WHAT “PQC” DOES AND DOES NOT MEAN
Bootstrap uses ML-KEM-768 to establish a preshared key, and rotation derives fresh PSKs from a hybrid X25519MLKEM768 TLS 1.3 control session.
The Linux kernel WireGuard dataplane still uses its native cryptography, including ChaCha20-Poly1305; it is not replaced with a new PQ-native VPN protocol.
Router/certificate identity authentication uses Ed25519 and therefore is not a post-quantum signature scheme.
No FIPS certification, production certification, zero-loss rekey or quantum-safe identity-signature assertion is made by the deployed configuration.
LEAST-PRIVILEGE OPERATIONS
BaseOS uses a PQC-managed default-deny firewall; StratiSTOR/StratiSERV firewalls are never modified by PQC Fabric. Use the native host OS firewall manager for approved management, encrypted underlay, BGP and enrollment permits.
Use separate SSH host keys per VM and individual operator credentials rather than cloned/shared private administrative keys.
Prefer pinned SSH host keys or strict known_hosts; independent certificate-fingerprint verification for manual enrollment.
Never introduce competing nftables ownership: BaseOS can use the PQC policy; StratiSTOR/StratiSERV retain exclusive firewall control in the host operating system.
Protect root-only PKI, WireGuard keys and rotation journals; use encrypted VM disks and controlled backup access.
FRR status queries require frrvty access on the privileged agent; membership can also modify FRR config.
Review existing FRR configuration before allowing the routing reconciler to manage /etc/frr/frr.conf.
NO IMPLICIT GLOBAL ROUTING AUTHORITY
Link enrollment and route authorization are separate. A BGP announcement does not grant WireGuard cryptokey permission; and an AllowedIPs entry does not automatically mean the prefix is advertised or policy-forwarded. This explicit separation is the primary authorization boundary for multi-site designs.
16. SERVICE AND REBOOT OPERATIONS
SERVICE INVENTORY
| Unit | Boot behavior |
|---|---|
| stratisystem-pqc-early-firewall | At boot, BaseOS applies its managed nftables policy. StratiSTOR/StratiSERV firewall policy is unchanged. |
| stratisystem-pqc-host | Runs host compliance checks at startup; does not alter firewall rules on StratiSTOR/StratiSERV. |
| stratisystem-pqc-routing | Enabled reconciliation service; harmless disabled JSON before routing activation. |
| stratisystem-pqc-agent | Enabled root-controlled agent; handles Unix API and rotation workers. |
| stratisystem-pqc-api | Enabled restricted HTTPS mTLS management proxy. |
| wg-quick@wg0 | Not enabled in ready-only; enabled by completed fabric enrollment. |
INSPECT SERVICE STATE
for unit in \
stratisystem-pqc-early-firewall \
stratisystem-pqc-host \
stratisystem-pqc-routing \
stratisystem-pqc-agent \
stratisystem-pqc-api wg-quick@wg0; do
printf '%-40s : ' "$unit"
systemctl is-enabled "$unit" 2>/dev/null || true
done
systemctl --failed
journalctl -b -u stratisystem-pqc-agent --no-pager -n 80
REBOOT AND RECOVERY VERIFICATION
Reboot one router at a time during validation. After each returns: confirm host compliance, WireGuard handshake, topology, FRR adjacency, IP rules/table 2001 and synchronized rotation generation. Dummy test interfaces are not reboot-persistent unless separately configured using NetworkManager.
stratisystem-pqcctl --local host check
wg show wg0
stratisystem-pqcctl --local routing status
stratisystem-pqcctl --local fabric topology
stratisystem-pqcctl --local fabric rotation-status
vtysh -c 'show bgp ipv4 unicast summary'
ip -4 rule show
ip -4 route show table 2001
| BOUNDARY | The current source implements service/config persistence but VM reboot and crash-injection recovery must be qualified in the deployment environment. “Enabled” alone is not evidence that a tunnel was restored. |
|---|
17. TROUBLESHOOTING PLAYBOOK
Start with the layer that failed. Preserve stable links and identities unless a controlled recovery procedure explicitly requires changes.
| Symptom | Likely cause / first action |
|---|---|
| ready_unconfigured, no wg0 | Expected before tunnel set + join. Assign a unique /32 on both appliances. |
| fabric tunnel set rejects address | An address or active wg0 already exists; use planned reprovisioning rather than overwrite. |
| fabric join fails host key | Trust mismatch or changed key; independently verify remote identity and inspect known_hosts. |
| routing apply says neighbor not authorized | WireGuard AllowedIPs must cover peer tunnel /32 and imported site ranges; validate live wg show and matching peer before BGP apply. |
| BGP shows Active | Confirm wg0 ping, TCP/179, FRR zebra next-hop route, ASN/update-source and both nodes applied. |
| routing status says vtysh permission denied | Check frrvty supplementary group and FRR file/socket permissions; root vtysh may work. |
| BGP Established but PfxRcd=0 | Basic routing examples advertise none; use authorized site-test JSON and local prefix exists. |
| ip route get chooses management gateway | No active policy or route; check ip rule, table 2001 and policy JSON. |
| ping: Cannot assign requested address | Source 10.10.10.1 or 10.20.20.1 not assigned; recreate sdtest0. |
| Routing table 2001 does not exist | routing apply did not finish or policy disabled; inspect apply error. |
| rotation generation not advancing | Check local agent /v1/status attempts, last_error, connectivity and journal phase. |
| Tunnel drops during rekey | Possible sequential PSK switch; inspect both generations and agent errors, do not reset blindly. |
| SSH connection times out during fabric join | BaseOS: open narrow destination enrollment lease. StratiSTOR/StratiSERV: use OS firewall administration to permit temporary TCP 22; CLI cannot create that exception. |
| Join reports enrollment_lease_close_warning | If tunnel_verified=true, peer enrollment succeeded. Inspect enrollment-status; a missing or expired temporary SSH exception is treated as already closed when the owning firewall reports it as absent. |
| Router-to-router UDP 51820 / TCP 9443 blocked | BaseOS: check enrolled peer allowlist and endpoint. StratiSTOR/StratiSERV: check OS-managed underlay firewall rules; PQC does not change them. |
| Admin port 9090 accepts no connections | Verify actual admin service listener and permitted administrator CIDRs in the owning host firewall. PQC Fabric does not install the TCP 9090 listener. |
| Unwanted underlay ICMP fails | Expected under BaseOS default-deny. On other products, behavior depends on their host firewall policy. |
| PQC command refuses to run | Verify the appliance is an approved StratiSYSTEM OS installation and use the installed administration CLI: ERROR: Must execute in a SteelDome StratiSYSTEM OS. Do not bypass the platform gate. |
| fabric enrollment-open fails on StratiSTOR or StratiSERV | Expected: host firewall is externally managed. Open TCP 22 temporarily using that product's firewall manager; remove exception after join. |
| Missing PQC nftables table on StratiSTOR or StratiSERV | Expected. No PQC firewall table is required on those products. Check host check and the OS firewall owner instead. |
MINIMUM DIAGNOSTIC BUNDLE: NO SECRETS
stratisystem-pqcctl --local host check
stratisystem-pqcctl --local fabric tunnel status
stratisystem-pqcctl --local fabric topology
stratisystem-pqcctl --local routing status
stratisystem-pqcctl --local fabric rotation-status
wg show wg0
ip -4 route show table main
ip -4 rule show
vtysh -c 'show bgp ipv4 unicast summary'
journalctl -b -u stratisystem-pqc-agent -n 80 --no-pager
Before sharing diagnostics, redact peer identifiers, public endpoints and local network plans as required by policy. Never share raw WireGuard config with PSKs, unredacted private keys, management-ca.key, kem768.seed or rotation journals.
18. BACKUP, RECOVERY AND CONTROLLED REMOVAL
BACK UP AND PROTECT
Create encrypted, access-controlled backups of host, agent, API and routing configuration, persistent WireGuard settings, trusted peer bindings, certificates and protected rotation state. Record active links, routing policies, certificate inventory and firewall ownership. Keep offline CA signing keys separate from appliance backups. Restore only after validating the target appliance identity and coordinating with its peers.
REMOVE A LINK
# On BOTH nodes, first disable rotation and allow any run to end
stratisystem-pqcctl --local fabric rotation-disable
stratisystem-pqcctl --local fabric rotation-status
# Then remove the named link on each router
stratisystem-pqcctl --local --link-id site-a-b fabric remove
Review and remove obsolete routing policy separately. Link deletion does not mean certificate revocation and is not a globally atomic operation. If a link must be re-created, verify its old state and identities rather than blindly deleting key files.
19. ACCEPTANCE TEST CHECKLIST
GATE A — APPLIANCE-READY (BEFORE CONFIGURING LINKS)
PQC Fabric services are installed and initialized; appliance status and host check report a healthy ready-only appliance.
host check compliant. BaseOS: PQC-owned nftables default-deny active. StratiSTOR/StratiSERV: firewall externally managed and unchanged.
fabric tunnel status returns ready_unconfigured; no wg0 or wg0.conf exists.
Agent/API/routing-management units are enabled; API health responds through approved credentials.
GATE B — ENROLLED SECURE TUNNEL
Two distinct tunnel /32 addresses were assigned.
fabric join confirms activated, mutual trust and tunnel_verified.
wg show reports recent handshakes and mutually correct AllowedIPs.
rotation-status is enabled; both sides agree on stable committed generation.
GATE C — ROUTES AND TRAFFIC POLICY
BGP neighbors are Established with only intended prefixes.
PBR rule 20001 and table 2001 exist and select wg0 for the approved source/destination.
Bidirectional sourced-site pings succeed; unrelated traffic remains denied.
An induced prefix withdrawal and reboot behave according to the approved fail-closed plan.
GATE D — RESILIENCE AND SECURITY
Multiple manual/automatic key rotations complete with traffic monitored.
Interrupted rotation/reboot recovery is validated in the target VM environment.
Administrative access is restricted, diagnostics contain no secrets, and the firewall configuration follows the host product ownership policy.
FRR configuration ownership and external VM HA assumptions have been reviewed.
APPENDIX A — OPERATOR COMMAND QUICK REFERENCE
# Inspect the installed appliance on each router
stratisystem-pqcctl --local appliance status
stratisystem-pqcctl --local host check
stratisystem-pqcctl --local fabric tunnel status
# If uninitialized, provision once after management network setup
stratisystem-pqcctl --local --bin-dir /usr/sbin appliance provision
# Router A / Router B: assign unique tunnel addresses locally
stratisystem-pqcctl --local --tunnel-address 10.250.0.1/32 fabric tunnel set
# On Router B use 10.250.0.2/32
# BaseOS only: Router B opens a temporary SSH enrollment lease
stratisystem-pqcctl --local --enrollment-source 192.168.59.201 \
--enrollment-minutes 10 fabric enrollment-open
# Router A: enroll with approved SSH host trust
stratisystem-pqcctl --local --ssh root@192.168.59.202 \
--link-id site-a-b fabric join
# Stage and apply operator-approved FRR/PBR JSON (per router)
stratisystem-pqcctl --local --data /root/routing.json routing set
stratisystem-pqcctl --local routing apply
# Validate connectivity, topology and key rotation
wg show wg0
stratisystem-pqcctl --local fabric topology
stratisystem-pqcctl --local routing status
stratisystem-pqcctl --local fabric rotation-status
APPENDIX B — TWO-ROUTER DEPLOYMENT RUNBOOK
This example assumes PQC Fabric is already available on both StratiSYSTEM OS appliances. Router A uses 192.168.59.201 / 10.250.0.1; Router B uses 192.168.59.202 / 10.250.0.2. BaseOS firewall steps are shown where applicable. For StratiSTOR/StratiSERV, obtain permits through the host firewall owner.
B.1 BOTH ROUTERS — VERIFY READY-ONLY STATE
# Run on Router A and Router B
stratisystem-pqcctl --local appliance status
stratisystem-pqcctl --local host check
stratisystem-pqcctl --local fabric tunnel status
# Only if PQC Fabric has not been initialized on this appliance:
stratisystem-pqcctl --local --bin-dir /usr/sbin appliance provision
# Confirm the initial ready-only state
stratisystem-pqcctl --local fabric tunnel status
stratisystem-pqcctl --local fabric status
systemctl is-active stratisystem-pqc-agent stratisystem-pqc-api
B.2 ASSIGN SEPARATE TUNNEL ADDRESSES
# Router A
stratisystem-pqcctl --local --tunnel-address 10.250.0.1/32 fabric tunnel set
# Router B
stratisystem-pqcctl --local --tunnel-address 10.250.0.2/32 fabric tunnel set
B.3 OPEN DESTINATION SSH LEASE AND ENROLL
# BASEOS: Router B only — open temporary SSH from Router A
stratisystem-pqcctl --local --enrollment-source 192.168.59.201 \
--enrollment-minutes 2 fabric enrollment-open
# StratiSTOR/StratiSERV: permit temporary TCP 22 in the HOST firewall.
# Router A: initial signed mutual enrollment
stratisystem-pqcctl --local --ssh root@192.168.59.202 \
--link-id site-a-b fabric join
# Router B: verify lease on BaseOS or remove host firewall permit.
B.4 ADD SITE NETWORKS LATER — NO SSH LEASE REQUIRED WHEN LOCAL
# Router A: allow traffic from remote Router B site
stratisystem-pqcctl --local --link-id site-a-b \
--allowed-ips 10.20.20.1/32 fabric authorize
# Router B: allow traffic from remote Router A site
stratisystem-pqcctl --local --link-id site-a-b \
--allowed-ips 10.10.10.1/32 fabric authorize
# Configure local FRR + PBR using operator-managed policy JSON
stratisystem-pqcctl --local --data /root/site-routing.json routing set
stratisystem-pqcctl --local routing apply
Create the site endpoints before attempting the sourced ping: Router A needs 10.10.10.1/32 on sdtest0; Router B needs 10.20.20.1/32. These dummy interfaces are lab-only and do not persist across reboot. Alternatively, use the project’s basic routing-router-a/b examples to establish BGP with zero site prefixes and no PBR policies.
B.5 VERIFY ENCRYPTED CONNECTIVITY, BGP, AND FIREWALL
wg show wg0
wg show wg0 allowed-ips
vtysh -c "show bgp ipv4 unicast summary"
stratisystem-pqcctl --local fabric topology
stratisystem-pqcctl --local fabric rotation-status
stratisystem-pqcctl --local routing status
stratisystem-pqcctl --local host check
# BaseOS only:
# nft list set inet stratisystem_pqc fabric4
B.6 POST-DEPLOYMENT ACCEPTANCE CRITERIA
| Check | Successful outcome |
|---|---|
| Ready-only appliance | Host compliant; fabric tunnel status = ready_unconfigured; no wg0 or peers. |
| Firewall before enrollment | admin4 limited; fabric4 and enrollment4 empty; no unsolicited external ports besides approved TCP 9090. |
| Enroll and close SSH | fabric join: ok=true and tunnel_verified=true; enrollment4 empty afterward. |
| Peer port grants | fabric4 contains the exact remote underlay /32; no broad management CIDR is added. |
| BGP basic mode | Established session; zero customer prefixes is expected with routing-router-a/b examples. |
| BGP + PBR site test | One permitted site prefix per router; PBR rule/table installed; two-way sourced ping succeeds. |
| Key rotation | Both peers report matching committed generation and stable phase after rotation. |
| Deauthorization | Removing final link revokes its underlay /32; routing disable removes BGP/forwarding accept rules. |
Operational boundary: PBR example table 2001 uses an explicit next-hop route. BGP route withdrawal alone does not guarantee removal of that policy route. Test fail-closed site forwarding, reboot recovery and lease expiry under real operating conditions before production approval.
APPENDIX C — CERTIFICATE ADMINISTRATION
Where the environment requires privately managed certificate authorities or role-based management credentials, use the supported PKI administration commands from a secured administration system. Protect CA private keys and distribute only approved certificates and trust material to appliances.
# Examples: secure administrator PKI workspace
stratisystem-pqcctl --pki-dir /secure/pqc-ca pki init
stratisystem-pqcctl --pki-dir /secure/pqc-ca \
--pki-name gw-a pki gateway
stratisystem-pqcctl --pki-dir /secure/pqc-ca \
--pki-name gw-a --pki-san 192.0.2.11 pki api
stratisystem-pqcctl --pki-dir /secure/pqc-ca \
--pki-name operator1 --pki-role pqc-admin pki client
For production use, validate certificate subject names, fingerprints, trust chains, expiry and access roles before enabling remote management. Never share a single operator private key across administrators.
APPENDIX D — NETWORK POLICY CHECKLIST
Firewall responsibility is determined by the StratiSYSTEM OS, not by whether a tunnel exists. If either StratiSTOR or StratiSERV is present, PQC Fabric never writes host nftables, even when BaseOS paths also exist.
| Check | BaseOS-managed | StratiSTOR / StratiSERV |
|---|---|---|
| Before enrollment | Verify admin TCP 9090, empty fabric4 | Verify approved host firewall allows management and future router ports |
| Temporary SSH | Use enrollment-open (1–15 min) | Use native OS firewall manager; enrollment-open cannot change rules |
| After enrollment | Check exact fabric4 underlay /32s | Verify host firewall permits 51820/UDP and 9443/TCP |
| After routing apply | Check BGP 179/tunnel forwarding if configured | OS firewall owner must permit BGP and forwarding |
| After peer removal | Verify revoked underlay permit | Revoke unneeded rules in host firewall policy |
| At reboot | Check early firewall and host check | Check external firewall; PQC early-firewall no-op |