From 494e8d1e3e3371832baf9926529cb8b1305c7b91 Mon Sep 17 00:00:00 2001 From: Kaushik Agrawal Date: Sun, 17 May 2026 15:47:13 -0400 Subject: [PATCH 01/10] Add auto-generated configuration documentation Documents the auto-generation lifecycle, two categories of subsystems (leaf-only vs leaf+metadata), how to take ownership of generated elements using the single-commit workflow, per-subsystem reference, protection mechanisms, and import/export behavior. Adds config_autogenerated.md and sidebar entry after config_basics. --- docs/config_autogenerated.md | 400 +++++++++++++++++++++++++++++++++++ sidebars.js | 15 +- 2 files changed, 408 insertions(+), 7 deletions(-) create mode 100644 docs/config_autogenerated.md diff --git a/docs/config_autogenerated.md b/docs/config_autogenerated.md new file mode 100644 index 0000000000..d6b37a9dd2 --- /dev/null +++ b/docs/config_autogenerated.md @@ -0,0 +1,400 @@ +--- +title: Auto-Generated Configuration +sidebar_label: Auto-Generated Configuration +--- + +During every `commit`, the SSR platform automatically generates certain configuration elements based on the current topology and feature configuration. These elements are removed and re-created on each commit by default, meaning any manual edits to them are lost unless you take explicit ownership first. + +This document covers what gets generated, what triggers it, how to prevent or customize it, and the internal mechanisms that control the lifecycle. + +## The Auto-Generation Lifecycle + +On every commit, the system runs a three-phase cycle: + +1. **Removal** — The system deletes all previously auto-generated elements so they can be rebuilt from scratch. There are two independent removal paths: + - **Element-level:** All services, service-routes, peers, adjacencies, tenants, and service-policies where `generated` is set to `true` are collected and removed. + - **Metadata-level:** A hidden authority metadata list (`authority > generated`) tracks elements created by certain subsystems (plugins, DHCP server KNI, port-forwarding, software-update). All paths recorded in that list are removed, and the metadata entries are cleared. + +2. **Generation** — Each subsystem builder runs and creates fresh elements. Before creating an element, the builder checks whether a matching element already exists with `generated` set to `false`. If it does, that element is treated as user-provisioned and generation is skipped. + +3. **Metadata update** — Newly generated elements from metadata-tracking subsystems are recorded in the authority metadata list for the next cycle. + +### Two Categories of Subsystem + +Not all subsystems use both removal paths. This distinction determines how to override elements: + +| Category | Subsystems | Removal Path | Override Method | +|----------|-----------|-------------|-----------------| +| **Leaf-only** | shared-service-route, conductor services, BGP services, DHCP relay, PIM/MSDP, alarm shelving, internal tenants | Element-level (`generated` leaf) only | Set `generated` to `false` directly | +| **Leaf + metadata** | Plugin builder, DHCP server (KNI), software-update, port-forwarding | Both element-level and metadata-level | Use `override-generated true` | + +:::tip +The PCLI automatically presents the correct command based on the element's category. Always use `override-generated` when it appears on the element. Only set `generated` to `false` directly when `override-generated` is not available (i.e., the `generated` leaf is visible instead). +::: + +## Taking Ownership of Auto-Generated Elements + +### Recommended: The `create config autogenerated` Single-Commit Workflow + +The most practical approach uses the `create config autogenerated` command to avoid a two-commit cycle: + +``` +admin@conductor> create config autogenerated +``` + +This runs the same generation logic as `commit` but **stages the results into the candidate configuration without committing**. You can then review, override, and customize elements before committing once. + +**Workflow:** + +1. Configure your triggers (neighborhoods, conductor-address, BGP neighbors, etc.) +2. Run `create config autogenerated` — auto-generated elements appear in the candidate +3. Enter config editing mode and navigate to elements you want to customize +4. Override those elements (see below) +5. Make your modifications +6. Commit **once** — the removal phase skips your overridden elements, and the generation phase sees them as user-provisioned + +During the commit, elements with `generated` set to `false` survive the removal phase and are skipped during regeneration, preserving your customizations in a single commit. + +:::note +If the underlying trigger configuration changes (e.g., new neighborhoods, new conductor addresses), re-run `create config autogenerated` to preview newly generated elements before committing. +::: + +### Overriding Leaf-Only Elements + +For elements generated by shared-service-route, conductor services, BGP, DHCP relay, PIM, or MSDP — the `generated` leaf is directly visible in the PCLI: + +``` +config + authority + router + service-route + generated false + exit + exit + exit +exit +``` + +Setting `generated` to `false` is sufficient. These subsystems only check the leaf on the element and do not use metadata tracking. + +### Overriding Metadata-Tracked Elements + +For elements generated by plugins, DHCP server (KNI), port-forwarding, or software-update — the PCLI shows the `override-generated` command instead of the `generated` leaf: + +``` +*admin@conductor# config +*admin@conductor (config)# authority +*admin@conductor (authority)# router +*admin@conductor (router)# node +*admin@conductor (node)# device-interface +*admin@conductor (device-interface)# override-generated true +Are you sure you want to make '' persistent? +It will no longer be auto-generated. [y/N]: +``` + +This performs two simultaneous actions: +1. Sets `persistent` to `true` in the metadata tracking entry — prevents metadata-based removal +2. Sets `generated` to `false` on the element — prevents element-level removal and causes the builder to skip regeneration + +:::warning +Both flags are required for full protection on metadata-tracked elements. Setting only `generated` to `false` is **unsafe** — the metadata removal path would still delete the element on the next commit. +::: + +**To revert** any override and re-enable auto-generation, run `override-generated false` (or set `generated` to `true` for leaf-only elements). On the next commit the element will be removed and re-generated by the system. + +### Pre-Provisioning Elements + +If you create an element with the **same name** that auto-generation would use before generation runs, the system detects it and skips generation. The manually created element has `generated` set to `false` by default, so it is treated as user-provisioned. + +This works for adjacencies, service-routes, and services. + +## Auto-Generated Configuration Reference + +### Shared Service Routes + +The shared-service-route feature generates two related sets of elements: the _peer_ and _adjacency_ objects that form the inter-router topology, and the peer-type _service-route_ objects that distribute service reachability across that topology. + +**Peers and adjacencies** + +| | | +|---|---| +| **Trigger** | _neighborhood_ configured on a forwarding _network-interface_ | +| **What is generated** | _peer_ objects between routers sharing the same neighborhood; _adjacency_ objects on both sides | +| **Category** | Leaf-only | + +Conditions for generation: +- The _network-interface_ must have `forwarding` set to `true` (default) and at least one _neighborhood_ entry +- Topology matching: `mesh` ↔ `mesh`/`hub`/`spoke`; `hub` ↔ `spoke`/`mesh`; `spoke` ↔ `hub`/`mesh` +- `peer-connectivity` must not be `outbound-only` on **both** sides +- `inter-router-security` must be set on any interface with a neighborhood + +| Method | Scope | Effect | +|--------|-------|--------| +| Remove _neighborhood_ from the interface | Per-interface | No adjacencies generated for that interface | +| Set `peer-connectivity` to `outbound-only` on both sides | Per-adjacency pair | Prevents that specific adjacency | +| Set `generated` to `false` on an adjacency or peer | Per-element | Takes ownership of that element | +| Pre-provision the adjacency before commit | Per-element | System detects it and skips generation | + +:::note +There is no global toggle. If neighborhoods are configured, peers and adjacencies **will** be generated unless overridden per-element. +::: + +**Service-routes** + +| | | +|---|---| +| **Trigger** | A router has a non-peer _service-route_ for a shared service, and peer routers exist | +| **What is generated** | Peer-type _service-route_ objects on remote routers pointing back to the source | +| **Category** | Leaf-only | + +Conditions for generation: +1. Service has `share-service-routes` set to `true` (default) +2. Source router has at least one non-peer service-route (e.g., next-hop) for the service +3. Service `application-type` is `generic` +4. Service `applies-to` allows the peer router +5. Authority is not using a shared-service-route repository + +| Method | Scope | Effect | +|--------|-------|--------| +| Set `share-service-routes` to `false` | Per-service | Prevents shared service-route generation for that service | +| Configure `applies-to` restrictions | Per-service | Limits which routers receive generated routes | +| Set `generated` to `false` on a service-route | Per-element | Takes ownership of that route | +| Pre-provision a service-route with the same name | Per-element | System skips generation for that route | + +--- + +### Conductor/Management Services + +| | | +|---|---| +| **Trigger** | `conductor-address` is configured on the authority | +| **What is generated** | Conductor reachability _service_, _service-policy_, _service-route_, and related _tenant_ objects | +| **Category** | Leaf-only | + +Generation is unconditional when any `conductor-address` is configured. There is no way to fully disable this category, but there are customization options and per-element overrides: + +| Method | Level | Effect | +|--------|-------|--------| +| `management-service-generation > service-route-type` | Authority or Router | Choose `paths-as-next-hop` (default) or `paths-as-service-route` | +| `management-service-generation > service-policy` | Authority or Router | Use a custom _service-policy_ instead of the auto-generated one | +| `management-service-generation > proxy` | Router only | Enable/disable proxy of public-to-private conductor addresses | +| Set `generated` to `false` on a conductor service or route | Per-element | Takes ownership of that element | + +--- + +### BGP Services and Service-Routes + +| | | +|---|---| +| **Trigger** | BGP neighbor transport configuration | +| **What is generated** | BGP peering _service_ and _service-route_ objects for BGP neighbor reachability | +| **Category** | Leaf-only | + +| Method | Scope | Effect | +|--------|-------|--------| +| Set `bgp-service-generation > disabled` | Per-BGP-neighbor | Fully prevents generation for that neighbor | +| Set `bgp-service-generation > service-policy` | Per-BGP-neighbor | Override the generated _service-policy_ | +| Set `bgp-service-generation > security-policy` | Per-BGP-neighbor | Override the generated security policy | +| Set `bgp-service-generation > route-reflector-client-mesh` | Authority | Generate service-route mesh for route reflector clients | +| Set `generated` to `false` on a BGP service | Per-element | Takes ownership of that service | + +BGP service generation is **fully disableable** per-neighbor using the `disabled` option. + +--- + +### DHCP Server KNI Device-Interfaces + +| | | +|---|---| +| **Trigger** | `host-service` of type `dhcp-server` configured on a _network-interface_ | +| **What is generated** | KNI _device-interface_ objects for DHCP server operation | +| **Category** | Leaf + metadata | + +| Setting | Level | Effect | +|---------|-------|--------| +| `dhcp-server-generated-address-pool` | Authority (`application-identification`) | Changes the address pool for generated KNI interfaces (default: `169.254.130.0/24`) | +| `override-generated true` on the KNI interface | Per-element | Takes ownership of that element | + +There is no flag to fully disable DHCP KNI generation. Remove the `dhcp-server` host-service to prevent generation. + +--- + +### DHCP Relay Services and Routes + +| | | +|---|---| +| **Trigger** | DHCP relay agent configured on a _network-interface_ | +| **What is generated** | DHCP relay _service_ and _service-route_ objects | +| **Category** | Leaf-only | + +| Method | Scope | Effect | +|--------|-------|--------| +| Remove DHCP relay configuration | Per-interface | Prevents generation | +| Set `generated` to `false` on the service or route | Per-element | Takes ownership of that element | + +--- + +### Application Identification (App-ID) Services + +| | | +|---|---| +| **Trigger** | `generate-categories` set to `true` on a _service_ | +| **What is generated** | Category-based child _service_ objects under the parent service | +| **Category** | Leaf-only | + +| Method | Scope | Effect | +|--------|-------|--------| +| Set `generate-categories` to `false` (default) | Per-service | Prevents category-based child service generation | +| Set `application-identification` to `disabled` | Per-service | Disables app-id entirely for that service | + +The default is `false` (disabled). Category services are only generated when explicitly opted-in. + +--- + +### PIM Multicast Services and Routes + +| | | +|---|---| +| **Trigger** | PIM routing configured on a router | +| **What is generated** | PIM multicast _service_ and _service-route_ objects | +| **Category** | Leaf-only | + +No independent disable flag. Remove the PIM configuration to prevent generation. Set `generated` to `false` per-element to take ownership. + +--- + +### MSDP Services and Routes + +| | | +|---|---| +| **Trigger** | MSDP routing configured | +| **What is generated** | MSDP peering _service_ and _service-route_ objects | +| **Category** | Leaf-only | + +No independent disable flag. Remove the MSDP configuration to prevent generation. Set `generated` to `false` per-element to take ownership. + +--- + +### Plugin-Generated Elements + +| | | +|---|---| +| **Trigger** | Varies by plugin | +| **What is generated** | Plugin-specific services, routes, and other configuration | +| **Category** | Leaf + metadata | + +Use `override-generated true` on any plugin-generated element to take ownership. + +--- + +### Software Update Proxy + +| | | +|---|---| +| **Trigger** | Managed routers exist in the authority | +| **What is generated** | Internal proxy configuration for software updates | +| **Category** | Leaf + metadata | + +This is a hidden, internally managed setting. It is unconditionally set when managed routers exist. There is no opt-out mechanism and no override is available. + +--- + +### Alarm Shelving + +| | | +|---|---| +| **Trigger** | Internal alarm shelving logic | +| **What is generated** | Alarm shelf entries | +| **Category** | Leaf-only | + +Set `generated` to `false` per-element to take ownership. + +--- + +### Internal Tenants + +| | | +|---|---| +| **Trigger** | Conductor services, BGP, or other internal features are active | +| **What is generated** | Internal tenants such as `_internal_`, `_bgp_speaker_` | +| **Category** | Leaf-only | + +:::warning +These tenants are required for the platform to function. Setting `generated` to `false` is technically possible but **not recommended** — it may impact platform functionality. +::: + +--- + +### Auto-Generated IDs + +| | | +|---|---| +| **Trigger** | Any config element missing a required ID field | +| **What is generated** | Unique IDs for config elements | + +This is a fundamental platform requirement. It cannot be disabled or overridden. + +--- + +## Protection Mechanisms in Detail + +This section provides deeper technical detail on how the two mechanisms interact. Most users can rely on the guidance above — the PCLI shows the correct command automatically. + +### The `generated` Leaf + +Every auto-generated element has a `generated` boolean: +- `generated true` — element is collected for removal during commit and regenerated +- `generated false` — element is skipped during both removal and regeneration + +### The Authority Metadata Tracking List + +A hidden list at `authority > generated` tracks elements created by certain subsystems. Each entry has a `persistent` flag: +- `persistent false` (default) — the element's path is collected for removal +- `persistent true` — the path is retained and NOT collected for removal + +### Interaction Matrix + +| State | Removed? | Regenerated? | Assessment | +|-------|:--------:|:------------:|------------| +| `generated true`, no metadata | Yes (leaf) | Yes | Normal leaf-only behavior | +| `generated false`, no metadata | No | No | **Safe** — fully protected | +| `generated true`, metadata `persistent false` | Yes (both paths) | Yes | Normal metadata-tracked behavior | +| `generated false`, metadata `persistent false` | Yes (metadata) | May be | **Unsafe** — metadata removal still deletes it | +| `generated false`, metadata `persistent true` | No | No | **Safe** — what `override-generated true` sets | +| `generated true`, metadata `persistent true` | Yes (leaf) | Yes | **Unsafe** — leaf removal still deletes it | + +### PCLI Visibility + +The `generated` leaf and `override-generated` command are mutually exclusive in the PCLI: +- If a metadata entry exists → `generated` leaf is hidden; `override-generated` is shown +- If no metadata entry exists → `generated` leaf is visible; `override-generated` is hidden + +## Import/Export Behavior + +The `export config` and `import config` PCLI commands save and restore the full configuration to/from a GZIP-compressed XML file on disk (stored in `/etc/128technology/config-exports/`). + +Both the `generated` leaf on individual elements **and** the `authority > generated` metadata list are **fully preserved** during export and import. The export serializes the entire configuration tree without filtering. + +This means: +- All auto-generated elements, their `generated` boolean values, and any `override-generated` state survive a round-trip export/import +- The `authority > generated` metadata entries (including `persistent` flags) are included +- The configuration behaves identically after import — the same PCLI commands are available, and the same override protections are in effect +- Elements with `generated true` will still be removed and re-generated on the next commit after import +- Elements previously overridden (`generated false` or `persistent true`) remain protected + +## Quick Reference + +| Element | Dedicated Disable Option | Per-Element Override | +|---------|-------------------------|---------------------| +| Shared service-routes | `share-service-routes false` | `generated false` | +| Shared service-route peers/adjacencies | Remove _neighborhood_ | `generated false` | +| Conductor/management services | No (customization knobs only) | `generated false` | +| BGP services | `bgp-service-generation > disabled` | `generated false` | +| DHCP relay services | Remove relay config | `generated false` | +| DHCP server KNI interfaces | Remove `dhcp-server` host-service | `override-generated true` | +| App-ID category services | `generate-categories false` (default) | `generated false` | +| PIM/MSDP services | Remove routing config | `generated false` | +| Plugin-generated elements | Varies by plugin | `override-generated true` | +| Internal tenants | No | `generated false` (not recommended) | +| Software-update proxy | No | Not available | +| Auto-generated IDs | No | Not available | diff --git a/sidebars.js b/sidebars.js index 2448b5b239..aab0d8075e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -125,7 +125,7 @@ module.exports = { "initialize_u-iso_device", "initialize_u-iso_adv_workflow", "sec-ztp-web-proxy", - "sec-conductor-onboard", + "sec-conductor-onboard", ], "Cloud / Hypervisor Installations": [ "supported_cloud_platforms", @@ -232,6 +232,7 @@ module.exports = { "label": "Administration", "items": [ "config_basics", + "config_autogenerated", "config_templates", "howto_local_config_override", "config_RBAC", @@ -376,10 +377,10 @@ module.exports = { "sec_hardening_guidelines", "sec_security_policy", "sec_adaptive_encrypt", - "sec_firewall_filtering", - "concepts_tpm", - "sec-config-seim-syslog", - "sec-ddos-resilience", + "sec_firewall_filtering", + "concepts_tpm", + "sec-config-seim-syslog", + "sec-ddos-resilience", "sec-usb-security", "sec-secure-boot", "concepts_config_integrity", @@ -388,8 +389,8 @@ module.exports = { "config_custom_certs", "sec-cert-based-encrypt", "cert_validation_requirements", - "sec_enhanced_key_mgmt", - "config_factory_reset", + "sec_enhanced_key_mgmt", + "config_factory_reset", ], }, { From 22215cea9504eccd56eaaf5866f43fd509e3334a Mon Sep 17 00:00:00 2001 From: Kaushik Agrawal Date: Sun, 17 May 2026 15:52:20 -0400 Subject: [PATCH 02/10] Rename Shared Service Routes to Peer Topology builder Use the more appropriate 'Peer Topology builder' term throughout the documentation instead of 'shared-service-route' to better reflect the internal component name and reduce confusion. --- docs/config_autogenerated.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/config_autogenerated.md b/docs/config_autogenerated.md index d6b37a9dd2..d7bae0d404 100644 --- a/docs/config_autogenerated.md +++ b/docs/config_autogenerated.md @@ -25,7 +25,7 @@ Not all subsystems use both removal paths. This distinction determines how to ov | Category | Subsystems | Removal Path | Override Method | |----------|-----------|-------------|-----------------| -| **Leaf-only** | shared-service-route, conductor services, BGP services, DHCP relay, PIM/MSDP, alarm shelving, internal tenants | Element-level (`generated` leaf) only | Set `generated` to `false` directly | +| **Leaf-only** | Peer Topology builder, conductor services, BGP services, DHCP relay, PIM/MSDP, alarm shelving, internal tenants | Element-level (`generated` leaf) only | Set `generated` to `false` directly | | **Leaf + metadata** | Plugin builder, DHCP server (KNI), software-update, port-forwarding | Both element-level and metadata-level | Use `override-generated true` | :::tip @@ -61,7 +61,7 @@ If the underlying trigger configuration changes (e.g., new neighborhoods, new co ### Overriding Leaf-Only Elements -For elements generated by shared-service-route, conductor services, BGP, DHCP relay, PIM, or MSDP — the `generated` leaf is directly visible in the PCLI: +For elements generated by the Peer Topology builder, conductor services, BGP, DHCP relay, PIM, or MSDP — the `generated` leaf is directly visible in the PCLI: ``` config @@ -110,9 +110,9 @@ This works for adjacencies, service-routes, and services. ## Auto-Generated Configuration Reference -### Shared Service Routes +### Peer Topology Builder -The shared-service-route feature generates two related sets of elements: the _peer_ and _adjacency_ objects that form the inter-router topology, and the peer-type _service-route_ objects that distribute service reachability across that topology. +The Peer Topology builder generates two related sets of elements: the _peer_ and _adjacency_ objects that form the inter-router topology, and the peer-type _service-route_ objects that distribute service reachability across that topology. **Peers and adjacencies** @@ -152,11 +152,11 @@ Conditions for generation: 2. Source router has at least one non-peer service-route (e.g., next-hop) for the service 3. Service `application-type` is `generic` 4. Service `applies-to` allows the peer router -5. Authority is not using a shared-service-route repository +5. Authority is not using a Peer Topology repository | Method | Scope | Effect | |--------|-------|--------| -| Set `share-service-routes` to `false` | Per-service | Prevents shared service-route generation for that service | +| Set `share-service-routes` to `false` | Per-service | Prevents Peer Topology builder route generation for that service | | Configure `applies-to` restrictions | Per-service | Limits which routers receive generated routes | | Set `generated` to `false` on a service-route | Per-element | Takes ownership of that route | | Pre-provision a service-route with the same name | Per-element | System skips generation for that route | @@ -386,8 +386,8 @@ This means: | Element | Dedicated Disable Option | Per-Element Override | |---------|-------------------------|---------------------| -| Shared service-routes | `share-service-routes false` | `generated false` | -| Shared service-route peers/adjacencies | Remove _neighborhood_ | `generated false` | +| Peer Topology builder service-routes | `share-service-routes false` | `generated false` | +| Peer Topology builder peers/adjacencies | Remove _neighborhood_ | `generated false` | | Conductor/management services | No (customization knobs only) | `generated false` | | BGP services | `bgp-service-generation > disabled` | `generated false` | | DHCP relay services | Remove relay config | `generated false` | From 6df07515d95726e40858f75e9835892bc18b5a14 Mon Sep 17 00:00:00 2001 From: Kaushik Agrawal Date: Sun, 17 May 2026 15:59:13 -0400 Subject: [PATCH 03/10] Add purpose statements to each per-config section Each auto-generated configuration section now includes a clear purpose statement explaining what that configuration accomplishes and why it exists, improving clarity for readers. --- docs/config_autogenerated.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/config_autogenerated.md b/docs/config_autogenerated.md index d7bae0d404..75c5fba4c5 100644 --- a/docs/config_autogenerated.md +++ b/docs/config_autogenerated.md @@ -112,6 +112,8 @@ This works for adjacencies, service-routes, and services. ### Peer Topology Builder +**Purpose:** Automatically establishes the inter-router topology and distributes service reachability information across peer routers, enabling dynamic topology discovery and service mesh capabilities without manual configuration. + The Peer Topology builder generates two related sets of elements: the _peer_ and _adjacency_ objects that form the inter-router topology, and the peer-type _service-route_ objects that distribute service reachability across that topology. **Peers and adjacencies** @@ -165,6 +167,8 @@ Conditions for generation: ### Conductor/Management Services +**Purpose:** Provides automatic management connectivity from managed routers back to the conductor system, enabling centralized configuration, monitoring, and software updates. + | | | |---|---| | **Trigger** | `conductor-address` is configured on the authority | @@ -184,6 +188,8 @@ Generation is unconditional when any `conductor-address` is configured. There is ### BGP Services and Service-Routes +**Purpose:** Automatically establishes reachability to BGP peers, enabling dynamic routing protocol operation and network convergence without manual service definition. + | | | |---|---| | **Trigger** | BGP neighbor transport configuration | @@ -204,6 +210,8 @@ BGP service generation is **fully disableable** per-neighbor using the `disabled ### DHCP Server KNI Device-Interfaces +**Purpose:** Automatically provisions kernel network interfaces required for the DHCP server subsystem to operate, handling the internal networking plumbing transparently. + | | | |---|---| | **Trigger** | `host-service` of type `dhcp-server` configured on a _network-interface_ | @@ -221,6 +229,8 @@ There is no flag to fully disable DHCP KNI generation. Remove the `dhcp-server` ### DHCP Relay Services and Routes +**Purpose:** Automatically provisions the DHCP relay service and reachability paths to DHCP servers, enabling DHCP client support on networks without a local DHCP server. + | | | |---|---| | **Trigger** | DHCP relay agent configured on a _network-interface_ | @@ -236,6 +246,8 @@ There is no flag to fully disable DHCP KNI generation. Remove the `dhcp-server` ### Application Identification (App-ID) Services +**Purpose:** Automatically creates granular service categories for application identification, allowing fine-grained traffic classification and policy enforcement without manual service creation. + | | | |---|---| | **Trigger** | `generate-categories` set to `true` on a _service_ | @@ -253,6 +265,8 @@ The default is `false` (disabled). Category services are only generated when exp ### PIM Multicast Services and Routes +**Purpose:** Automatically establishes reachability for Protocol Independent Multicast (PIM) control traffic, enabling multicast routing operation across the network. + | | | |---|---| | **Trigger** | PIM routing configured on a router | @@ -265,6 +279,8 @@ No independent disable flag. Remove the PIM configuration to prevent generation. ### MSDP Services and Routes +**Purpose:** Automatically provisions Multicast Source Discovery Protocol (MSDP) peering connectivity, enabling inter-domain multicast source discovery and reachability. + | | | |---|---| | **Trigger** | MSDP routing configured | @@ -277,6 +293,8 @@ No independent disable flag. Remove the MSDP configuration to prevent generation ### Plugin-Generated Elements +**Purpose:** Allows third-party plugins to extend the platform by automatically generating plugin-specific services, routes, and configuration elements as needed. + | | | |---|---| | **Trigger** | Varies by plugin | @@ -289,6 +307,8 @@ Use `override-generated true` on any plugin-generated element to take ownership. ### Software Update Proxy +**Purpose:** Automatically configures internal proxy settings for software updates on managed routers, ensuring seamless update delivery without manual configuration. + | | | |---|---| | **Trigger** | Managed routers exist in the authority | @@ -301,6 +321,8 @@ This is a hidden, internally managed setting. It is unconditionally set when man ### Alarm Shelving +**Purpose:** Automatically manages alarm suppression (shelving) based on internal platform logic, suppressing non-critical alarms during expected operational conditions. + | | | |---|---| | **Trigger** | Internal alarm shelving logic | @@ -313,6 +335,8 @@ Set `generated` to `false` per-element to take ownership. ### Internal Tenants +**Purpose:** Automatically provisions internal logical containers (tenants) for platform services and features that require tenant isolation without burdening users with these internal details. + | | | |---|---| | **Trigger** | Conductor services, BGP, or other internal features are active | @@ -327,6 +351,8 @@ These tenants are required for the platform to function. Setting `generated` to ### Auto-Generated IDs +**Purpose:** Automatically assigns unique identifiers to configuration elements when not explicitly provided, ensuring all config elements have required IDs without manual assignment. + | | | |---|---| | **Trigger** | Any config element missing a required ID field | From 46ac50d1bb509a2176d7cbc8d6fe345db8b00fab Mon Sep 17 00:00:00 2001 From: Kaushik Agrawal Date: Sun, 17 May 2026 16:00:53 -0400 Subject: [PATCH 04/10] Convert Purpose statements to intro paragraphs Remove Purpose labels and integrate them as natural intro paragraphs for each configuration section. Combine with existing intro text where applicable. --- docs/config_autogenerated.md | 45 +++++++++++------------------------- 1 file changed, 13 insertions(+), 32 deletions(-) diff --git a/docs/config_autogenerated.md b/docs/config_autogenerated.md index 75c5fba4c5..31b92cafee 100644 --- a/docs/config_autogenerated.md +++ b/docs/config_autogenerated.md @@ -112,9 +112,7 @@ This works for adjacencies, service-routes, and services. ### Peer Topology Builder -**Purpose:** Automatically establishes the inter-router topology and distributes service reachability information across peer routers, enabling dynamic topology discovery and service mesh capabilities without manual configuration. - -The Peer Topology builder generates two related sets of elements: the _peer_ and _adjacency_ objects that form the inter-router topology, and the peer-type _service-route_ objects that distribute service reachability across that topology. +The Peer Topology builder automatically establishes the inter-router topology and distributes service reachability information across peer routers, enabling dynamic topology discovery and service mesh capabilities without manual configuration. It generates two related sets of elements: the _peer_ and _adjacency_ objects that form the inter-router topology, and the peer-type _service-route_ objects that distribute service reachability across that topology. **Peers and adjacencies** @@ -167,7 +165,7 @@ Conditions for generation: ### Conductor/Management Services -**Purpose:** Provides automatic management connectivity from managed routers back to the conductor system, enabling centralized configuration, monitoring, and software updates. +The Conductor/Management Services subsystem provides automatic management connectivity from managed routers back to the conductor system, enabling centralized configuration, monitoring, and software updates. Generation is unconditional when any `conductor-address` is configured. There is no way to fully disable this category, but there are customization options and per-element overrides: | | | |---|---| @@ -175,8 +173,6 @@ Conditions for generation: | **What is generated** | Conductor reachability _service_, _service-policy_, _service-route_, and related _tenant_ objects | | **Category** | Leaf-only | -Generation is unconditional when any `conductor-address` is configured. There is no way to fully disable this category, but there are customization options and per-element overrides: - | Method | Level | Effect | |--------|-------|--------| | `management-service-generation > service-route-type` | Authority or Router | Choose `paths-as-next-hop` (default) or `paths-as-service-route` | @@ -188,7 +184,7 @@ Generation is unconditional when any `conductor-address` is configured. There is ### BGP Services and Service-Routes -**Purpose:** Automatically establishes reachability to BGP peers, enabling dynamic routing protocol operation and network convergence without manual service definition. +The BGP subsystem automatically establishes reachability to BGP peers, enabling dynamic routing protocol operation and network convergence without manual service definition. | | | |---|---| @@ -210,7 +206,7 @@ BGP service generation is **fully disableable** per-neighbor using the `disabled ### DHCP Server KNI Device-Interfaces -**Purpose:** Automatically provisions kernel network interfaces required for the DHCP server subsystem to operate, handling the internal networking plumbing transparently. +The DHCP server subsystem automatically provisions kernel network interfaces required for DHCP server operation, handling the internal networking plumbing transparently. | | | |---|---| @@ -229,7 +225,7 @@ There is no flag to fully disable DHCP KNI generation. Remove the `dhcp-server` ### DHCP Relay Services and Routes -**Purpose:** Automatically provisions the DHCP relay service and reachability paths to DHCP servers, enabling DHCP client support on networks without a local DHCP server. +The DHCP relay subsystem automatically provisions the DHCP relay service and reachability paths to DHCP servers, enabling DHCP client support on networks without a local DHCP server. | | | |---|---| @@ -246,7 +242,7 @@ There is no flag to fully disable DHCP KNI generation. Remove the `dhcp-server` ### Application Identification (App-ID) Services -**Purpose:** Automatically creates granular service categories for application identification, allowing fine-grained traffic classification and policy enforcement without manual service creation. +The App-ID subsystem automatically creates granular service categories for application identification, allowing fine-grained traffic classification and policy enforcement without manual service creation. | | | |---|---| @@ -265,7 +261,7 @@ The default is `false` (disabled). Category services are only generated when exp ### PIM Multicast Services and Routes -**Purpose:** Automatically establishes reachability for Protocol Independent Multicast (PIM) control traffic, enabling multicast routing operation across the network. +The PIM subsystem automatically establishes reachability for Protocol Independent Multicast (PIM) control traffic, enabling multicast routing operation across the network. | | | |---|---| @@ -279,7 +275,7 @@ No independent disable flag. Remove the PIM configuration to prevent generation. ### MSDP Services and Routes -**Purpose:** Automatically provisions Multicast Source Discovery Protocol (MSDP) peering connectivity, enabling inter-domain multicast source discovery and reachability. +The MSDP subsystem automatically provisions Multicast Source Discovery Protocol (MSDP) peering connectivity, enabling inter-domain multicast source discovery and reachability. | | | |---|---| @@ -293,7 +289,7 @@ No independent disable flag. Remove the MSDP configuration to prevent generation ### Plugin-Generated Elements -**Purpose:** Allows third-party plugins to extend the platform by automatically generating plugin-specific services, routes, and configuration elements as needed. +Plugins extend the platform by automatically generating plugin-specific services, routes, and configuration elements as needed. | | | |---|---| @@ -307,21 +303,13 @@ Use `override-generated true` on any plugin-generated element to take ownership. ### Software Update Proxy -**Purpose:** Automatically configures internal proxy settings for software updates on managed routers, ensuring seamless update delivery without manual configuration. - -| | | -|---|---| -| **Trigger** | Managed routers exist in the authority | -| **What is generated** | Internal proxy configuration for software updates | -| **Category** | Leaf + metadata | - -This is a hidden, internally managed setting. It is unconditionally set when managed routers exist. There is no opt-out mechanism and no override is available. +The software update subsystem automatically configures internal proxy settings for software updates on managed routers, ensuring seamless update delivery without manual configuration. This is a hidden, internally managed setting. It is unconditionally set when managed routers exist. There is no opt-out mechanism and no override is available. --- ### Alarm Shelving -**Purpose:** Automatically manages alarm suppression (shelving) based on internal platform logic, suppressing non-critical alarms during expected operational conditions. +The alarm shelving subsystem automatically manages alarm suppression (shelving) based on internal platform logic, suppressing non-critical alarms during expected operational conditions. | | | |---|---| @@ -335,7 +323,7 @@ Set `generated` to `false` per-element to take ownership. ### Internal Tenants -**Purpose:** Automatically provisions internal logical containers (tenants) for platform services and features that require tenant isolation without burdening users with these internal details. +The platform automatically provisions internal logical containers (tenants) for services and features that require tenant isolation without burdening users with these internal details. | | | |---|---| @@ -351,14 +339,7 @@ These tenants are required for the platform to function. Setting `generated` to ### Auto-Generated IDs -**Purpose:** Automatically assigns unique identifiers to configuration elements when not explicitly provided, ensuring all config elements have required IDs without manual assignment. - -| | | -|---|---| -| **Trigger** | Any config element missing a required ID field | -| **What is generated** | Unique IDs for config elements | - -This is a fundamental platform requirement. It cannot be disabled or overridden. +The platform automatically assigns unique identifiers to configuration elements when not explicitly provided, ensuring all config elements have required IDs without manual assignment. This is a fundamental platform requirement. It cannot be disabled or overridden. --- From 19997f265657dfb0e06f38468d01945c4633397f Mon Sep 17 00:00:00 2001 From: Kaushik Agrawal Date: Sun, 17 May 2026 16:03:41 -0400 Subject: [PATCH 05/10] Add Management Over Forwarding Interface (MOFI) services section Documents MOFI auto-generation for NTP, DNS, SNMP, Syslog, IPFIX, HTTP-HTTPS, and Audit services. Includes trigger, generated elements, override methods, and quick reference entry. --- docs/config_autogenerated.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/config_autogenerated.md b/docs/config_autogenerated.md index 31b92cafee..c1cb86c24a 100644 --- a/docs/config_autogenerated.md +++ b/docs/config_autogenerated.md @@ -343,6 +343,40 @@ The platform automatically assigns unique identifiers to configuration elements --- +### Management Over Forwarding Interface (MOFI) Services + +The MOFI builder automatically provisions management services for various network management and operational functions, enabling these services to be delivered over forwarding interfaces (data plane) when management interfaces are not available. This provides management connectivity through active data paths. + +| | | +|---|---| +| **Trigger** | A _network-interface_ configured with `management: true` on a forwarding interface | +| **What is generated** | Services and service-routes for NTP, DNS, SNMP, Syslog, IPFIX, HTTP-HTTPS (package updates), and Audit functions | +| **Category** | Leaf-only | + +The builder generates services for the following management traffic types: + +| Service Type | Purpose | +|---|---| +| NTP | Network Time Protocol for clock synchronization | +| DNS | Domain Name System for name resolution | +| SNMP | Simple Network Management Protocol for device management | +| Syslog | System logging for centralized log collection | +| IPFIX | IP Flow Information Export for flow telemetry | +| HTTP-HTTPS | Software package downloads for system updates | +| Audit | Audit event forwarding for compliance logging | + +| Method | Scope | Effect | +|--------|-------|--------| +| Remove `management: true` from the interface | Per-interface | Prevents MOFI service generation for that interface | +| Disable management services in authority config | Authority | Prevents generation globally (if supported) | +| Set `generated` to `false` on a MOFI service or route | Per-element | Takes ownership of that element | + +:::note +MOFI services are generated with the lowest priority to ensure they don't override user-configured services with the same names. Pre-provisioning a service with the same name before generation will prevent the auto-generated version from being created. +::: + +--- + ## Protection Mechanisms in Detail This section provides deeper technical detail on how the two mechanisms interact. Most users can rely on the guidance above — the PCLI shows the correct command automatically. @@ -396,6 +430,7 @@ This means: | Peer Topology builder service-routes | `share-service-routes false` | `generated false` | | Peer Topology builder peers/adjacencies | Remove _neighborhood_ | `generated false` | | Conductor/management services | No (customization knobs only) | `generated false` | +| MOFI services (NTP, DNS, SNMP, etc.) | Remove `management: true` from interface | `generated false` | | BGP services | `bgp-service-generation > disabled` | `generated false` | | DHCP relay services | Remove relay config | `generated false` | | DHCP server KNI interfaces | Remove `dhcp-server` host-service | `override-generated true` | From 804eeec6ae0965fc37103659c49cb670e8cf40b5 Mon Sep 17 00:00:00 2001 From: Kaushik Agrawal Date: Sun, 17 May 2026 16:04:27 -0400 Subject: [PATCH 06/10] Move MOFI services section next to Conductor services Repositioned the Management Over Forwarding Interface (MOFI) section to immediately follow the Conductor/Management Services section, as MOFI services are logically part of the management infrastructure. --- docs/config_autogenerated.md | 68 ++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/docs/config_autogenerated.md b/docs/config_autogenerated.md index c1cb86c24a..72f86f8174 100644 --- a/docs/config_autogenerated.md +++ b/docs/config_autogenerated.md @@ -182,6 +182,40 @@ The Conductor/Management Services subsystem provides automatic management connec --- +### Management Over Forwarding Interface (MOFI) Services + +The MOFI builder automatically provisions management services for various network management and operational functions, enabling these services to be delivered over forwarding interfaces (data plane) when management interfaces are not available. This provides management connectivity through active data paths. + +| | | +|---|---| +| **Trigger** | A _network-interface_ configured with `management: true` on a forwarding interface | +| **What is generated** | Services and service-routes for NTP, DNS, SNMP, Syslog, IPFIX, HTTP-HTTPS (package updates), and Audit functions | +| **Category** | Leaf-only | + +The builder generates services for the following management traffic types: + +| Service Type | Purpose | +|---|---| +| NTP | Network Time Protocol for clock synchronization | +| DNS | Domain Name System for name resolution | +| SNMP | Simple Network Management Protocol for device management | +| Syslog | System logging for centralized log collection | +| IPFIX | IP Flow Information Export for flow telemetry | +| HTTP-HTTPS | Software package downloads for system updates | +| Audit | Audit event forwarding for compliance logging | + +| Method | Scope | Effect | +|--------|-------|--------| +| Remove `management: true` from the interface | Per-interface | Prevents MOFI service generation for that interface | +| Disable management services in authority config | Authority | Prevents generation globally (if supported) | +| Set `generated` to `false` on a MOFI service or route | Per-element | Takes ownership of that element | + +:::note +MOFI services are generated with the lowest priority to ensure they don't override user-configured services with the same names. Pre-provisioning a service with the same name before generation will prevent the auto-generated version from being created. +::: + +--- + ### BGP Services and Service-Routes The BGP subsystem automatically establishes reachability to BGP peers, enabling dynamic routing protocol operation and network convergence without manual service definition. @@ -343,40 +377,6 @@ The platform automatically assigns unique identifiers to configuration elements --- -### Management Over Forwarding Interface (MOFI) Services - -The MOFI builder automatically provisions management services for various network management and operational functions, enabling these services to be delivered over forwarding interfaces (data plane) when management interfaces are not available. This provides management connectivity through active data paths. - -| | | -|---|---| -| **Trigger** | A _network-interface_ configured with `management: true` on a forwarding interface | -| **What is generated** | Services and service-routes for NTP, DNS, SNMP, Syslog, IPFIX, HTTP-HTTPS (package updates), and Audit functions | -| **Category** | Leaf-only | - -The builder generates services for the following management traffic types: - -| Service Type | Purpose | -|---|---| -| NTP | Network Time Protocol for clock synchronization | -| DNS | Domain Name System for name resolution | -| SNMP | Simple Network Management Protocol for device management | -| Syslog | System logging for centralized log collection | -| IPFIX | IP Flow Information Export for flow telemetry | -| HTTP-HTTPS | Software package downloads for system updates | -| Audit | Audit event forwarding for compliance logging | - -| Method | Scope | Effect | -|--------|-------|--------| -| Remove `management: true` from the interface | Per-interface | Prevents MOFI service generation for that interface | -| Disable management services in authority config | Authority | Prevents generation globally (if supported) | -| Set `generated` to `false` on a MOFI service or route | Per-element | Takes ownership of that element | - -:::note -MOFI services are generated with the lowest priority to ensure they don't override user-configured services with the same names. Pre-provisioning a service with the same name before generation will prevent the auto-generated version from being created. -::: - ---- - ## Protection Mechanisms in Detail This section provides deeper technical detail on how the two mechanisms interact. Most users can rely on the guidance above — the PCLI shows the correct command automatically. From c2a2ba7950caf84be63efc3c18cb19b1953c8ab7 Mon Sep 17 00:00:00 2001 From: Kaushik Agrawal Date: Sun, 17 May 2026 16:05:08 -0400 Subject: [PATCH 07/10] Rename Conductor/Management Services to Conductor Services Since management services (NTP, DNS, SNMP, etc.) are now covered by the MOFI section, simplify the Conductor section name to reflect its focus on conductor connectivity and configuration management. --- docs/config_autogenerated.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/config_autogenerated.md b/docs/config_autogenerated.md index 72f86f8174..bc1921016b 100644 --- a/docs/config_autogenerated.md +++ b/docs/config_autogenerated.md @@ -163,9 +163,9 @@ Conditions for generation: --- -### Conductor/Management Services +### Conductor Services -The Conductor/Management Services subsystem provides automatic management connectivity from managed routers back to the conductor system, enabling centralized configuration, monitoring, and software updates. Generation is unconditional when any `conductor-address` is configured. There is no way to fully disable this category, but there are customization options and per-element overrides: +The Conductor Services subsystem provides automatic connectivity from managed routers back to the conductor system, enabling centralized configuration, monitoring, and software updates. Generation is unconditional when any `conductor-address` is configured. There is no way to fully disable this category, but there are customization options and per-element overrides: | | | |---|---| @@ -429,7 +429,7 @@ This means: |---------|-------------------------|---------------------| | Peer Topology builder service-routes | `share-service-routes false` | `generated false` | | Peer Topology builder peers/adjacencies | Remove _neighborhood_ | `generated false` | -| Conductor/management services | No (customization knobs only) | `generated false` | +| Conductor services | No (customization knobs only) | `generated false` | | MOFI services (NTP, DNS, SNMP, etc.) | Remove `management: true` from interface | `generated false` | | BGP services | `bgp-service-generation > disabled` | `generated false` | | DHCP relay services | Remove relay config | `generated false` | From f71a425948ee3b414b0942a3f6c428575197401a Mon Sep 17 00:00:00 2001 From: Kaushik Agrawal Date: Sun, 17 May 2026 16:12:36 -0400 Subject: [PATCH 08/10] Add SCO and Resource Groups sections; reorganize by user-facing vs infrastructure config - Add Secure Conductor Onboarding (SCO) section documenting auto-generation of operating mode and pre-shared keys - Add Resource Groups section documenting automatic resource-to-role associations for RBAC with list of supported resource types - Reorganize per-config sections into two clear groupings: * User-Facing Configuration: elements users typically interact with * Infrastructure and System Configuration: internal platform-managed settings - Split Quick Reference table to match the new section organization --- docs/config_autogenerated.md | 94 ++++++++++++++++++++++++++++++------ 1 file changed, 80 insertions(+), 14 deletions(-) diff --git a/docs/config_autogenerated.md b/docs/config_autogenerated.md index bc1921016b..d297394ae9 100644 --- a/docs/config_autogenerated.md +++ b/docs/config_autogenerated.md @@ -110,7 +110,11 @@ This works for adjacencies, service-routes, and services. ## Auto-Generated Configuration Reference -### Peer Topology Builder +### User-Facing Configuration + +This section covers auto-generated configuration that users typically interact with and may need to customize or override. + +#### Peer Topology Builder The Peer Topology builder automatically establishes the inter-router topology and distributes service reachability information across peer routers, enabling dynamic topology discovery and service mesh capabilities without manual configuration. It generates two related sets of elements: the _peer_ and _adjacency_ objects that form the inter-router topology, and the peer-type _service-route_ objects that distribute service reachability across that topology. @@ -163,7 +167,7 @@ Conditions for generation: --- -### Conductor Services +#### Conductor Services The Conductor Services subsystem provides automatic connectivity from managed routers back to the conductor system, enabling centralized configuration, monitoring, and software updates. Generation is unconditional when any `conductor-address` is configured. There is no way to fully disable this category, but there are customization options and per-element overrides: @@ -182,7 +186,7 @@ The Conductor Services subsystem provides automatic connectivity from managed ro --- -### Management Over Forwarding Interface (MOFI) Services +#### Management Over Forwarding Interface (MOFI) Services The MOFI builder automatically provisions management services for various network management and operational functions, enabling these services to be delivered over forwarding interfaces (data plane) when management interfaces are not available. This provides management connectivity through active data paths. @@ -216,7 +220,7 @@ MOFI services are generated with the lowest priority to ensure they don't overri --- -### BGP Services and Service-Routes +#### BGP Services and Service-Routes The BGP subsystem automatically establishes reachability to BGP peers, enabling dynamic routing protocol operation and network convergence without manual service definition. @@ -238,7 +242,7 @@ BGP service generation is **fully disableable** per-neighbor using the `disabled --- -### DHCP Server KNI Device-Interfaces +#### DHCP Server KNI Device-Interfaces The DHCP server subsystem automatically provisions kernel network interfaces required for DHCP server operation, handling the internal networking plumbing transparently. @@ -257,7 +261,7 @@ There is no flag to fully disable DHCP KNI generation. Remove the `dhcp-server` --- -### DHCP Relay Services and Routes +#### DHCP Relay Services and Routes The DHCP relay subsystem automatically provisions the DHCP relay service and reachability paths to DHCP servers, enabling DHCP client support on networks without a local DHCP server. @@ -274,7 +278,7 @@ The DHCP relay subsystem automatically provisions the DHCP relay service and rea --- -### Application Identification (App-ID) Services +#### Application Identification (App-ID) Services The App-ID subsystem automatically creates granular service categories for application identification, allowing fine-grained traffic classification and policy enforcement without manual service creation. @@ -293,7 +297,7 @@ The default is `false` (disabled). Category services are only generated when exp --- -### PIM Multicast Services and Routes +#### PIM Multicast Services and Routes The PIM subsystem automatically establishes reachability for Protocol Independent Multicast (PIM) control traffic, enabling multicast routing operation across the network. @@ -307,7 +311,7 @@ No independent disable flag. Remove the PIM configuration to prevent generation. --- -### MSDP Services and Routes +#### MSDP Services and Routes The MSDP subsystem automatically provisions Multicast Source Discovery Protocol (MSDP) peering connectivity, enabling inter-domain multicast source discovery and reachability. @@ -321,7 +325,7 @@ No independent disable flag. Remove the MSDP configuration to prevent generation --- -### Plugin-Generated Elements +#### Plugin-Generated Elements Plugins extend the platform by automatically generating plugin-specific services, routes, and configuration elements as needed. @@ -335,13 +339,66 @@ Use `override-generated true` on any plugin-generated element to take ownership. --- -### Software Update Proxy +### Infrastructure and System Configuration + +This section covers auto-generated configuration managed by the platform for internal operations. Most users do not need to interact with or override these settings. + +#### Software Update Proxy The software update subsystem automatically configures internal proxy settings for software updates on managed routers, ensuring seamless update delivery without manual configuration. This is a hidden, internally managed setting. It is unconditionally set when managed routers exist. There is no opt-out mechanism and no override is available. --- -### Alarm Shelving +#### Secure Conductor Onboarding (SCO) + +The SCO subsystem automatically manages the secure onboarding mode for routers and configures pre-shared keys (PSK) required for secure conductor communication. This enables secure, automated onboarding of managed routers without manual key management. + +| | | +|---|---| +| **Trigger** | Routers with `system/secure-conductor-onboarding/mode` configured | +| **What is generated** | SCO operating mode (EXCLUSIVE or DISABLED) and pre-shared keys for routers | +| **Category** | Leaf-only | + +| Method | Scope | Effect | +|--------|-------|--------| +| Set `secure-conductor-onboarding > mode` to `disabled` | Per-router | Disables SCO for that router | +| Set `secure-conductor-onboarding > mode` to `exclusive` | Per-router | Enables SCO and triggers PSK generation | + +:::note +SCO operates at the system level and is automatically managed based on the configured operating mode. PSKs are only generated when SCO is enabled and are required for the conductor to authenticate the router. +::: + +--- + +#### Resource Groups + +The Resource Groups subsystem automatically associates configuration resources (routers, services, tenants, security profiles, etc.) with role-based access control (RBAC) resource groups. This enables policy enforcement for resource group-scoped access controls without manual resource enumeration. + +| | | +|---|---| +| **Trigger** | Configuration resources exist in the authority; roles define resource groups | +| **What is generated** | Resource entries in roles linking to configuration objects | +| **Category** | Leaf-only | + +Supported resource types include: +- Network elements (routers, districts) +- Services and traffic policies (services, service-classes, traffic-profiles) +- Security and access (tenants, security profiles, LDAP servers) +- Operational configuration (alarm shelves, performance profiles, DSCP maps, IPFIX collectors) +- Extensibility (STEP repos, PCLI aliases, session-types) + +| Method | Scope | Effect | +|--------|-------|--------| +| Pre-provision resources with specific names | Per-resource | System detects them and skips auto-generation | +| Set `generated` to `false` on a resource entry | Per-element | Takes ownership of that resource entry | + +:::note +Resource groups are generated with lowest priority; user-provisioned resources with matching names prevent auto-generation. This enables administrators to define custom resource mappings when needed. +::: + +--- + +#### Alarm Shelving The alarm shelving subsystem automatically manages alarm suppression (shelving) based on internal platform logic, suppressing non-critical alarms during expected operational conditions. @@ -355,7 +412,7 @@ Set `generated` to `false` per-element to take ownership. --- -### Internal Tenants +#### Internal Tenants The platform automatically provisions internal logical containers (tenants) for services and features that require tenant isolation without burdening users with these internal details. @@ -371,7 +428,7 @@ These tenants are required for the platform to function. Setting `generated` to --- -### Auto-Generated IDs +#### Auto-Generated IDs The platform automatically assigns unique identifiers to configuration elements when not explicitly provided, ensuring all config elements have required IDs without manual assignment. This is a fundamental platform requirement. It cannot be disabled or overridden. @@ -425,6 +482,8 @@ This means: ## Quick Reference +### User-Facing Configuration + | Element | Dedicated Disable Option | Per-Element Override | |---------|-------------------------|---------------------| | Peer Topology builder service-routes | `share-service-routes false` | `generated false` | @@ -437,6 +496,13 @@ This means: | App-ID category services | `generate-categories false` (default) | `generated false` | | PIM/MSDP services | Remove routing config | `generated false` | | Plugin-generated elements | Varies by plugin | `override-generated true` | + +### Infrastructure and System Configuration + +| Element | Dedicated Disable Option | Per-Element Override | +|---------|-------------------------|---------------------| +| Secure Conductor Onboarding (SCO) | Set `mode` to `disabled` | Not typically overridden | +| Resource Groups | Pre-provision resources | `generated false` | | Internal tenants | No | `generated false` (not recommended) | | Software-update proxy | No | Not available | | Auto-generated IDs | No | Not available | From 144d99721dfb62275f867987a64ff16e27a39fec Mon Sep 17 00:00:00 2001 From: Kaushik Agrawal Date: Mon, 18 May 2026 11:59:23 -0400 Subject: [PATCH 09/10] Address PR #1018 review feedback - Replace empty table headers (| | |) with Field/Description headers - Add closing periods to table cells and lists with internal punctuation - Remove unnecessary horizontal rules between same-level subsections - Fix voice: 'users typically interact' -> 'you typically interact' - Capitalize after colon in Peer Topology paragraph - Title Case heading: 'Peers and Adjacencies' - Remove 'hidden' from metadata list description in overview - Reword BGP disable sentence per reviewer suggestion - Add 'How To Identify Auto-Generated Elements' subsection to intro - Update copilot-instructions.md with new style rules from review --- .github/copilot-instructions.md | 10 ++ docs/config_autogenerated.md | 174 +++++++++++++++----------------- 2 files changed, 92 insertions(+), 92 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 810aa068f8..b82a29ccc9 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -138,6 +138,16 @@ Add the doc id to the appropriate section of [sidebars.js](../sidebars.js). Do * - *router* — an SSR data-plane node (lowercase). - *authority* — the top-level config domain. - *PCLI* — the SSR command-line interface. +- **Punctuation in lists and tables:** + - If **any** entry in a bulleted list or table column contains internal punctuation (comma, colon, semi-colon), **every** entry in that list or column must end with a period. + - Exception: entries that are only one or two words, or are names/categories (e.g., column headers, labels) do not require a closing period. + - *Good:* `| Prevents generation for that neighbor. |` (other rows have commas) + - *Bad:* `| Prevents generation for that neighbor |` (missing period when siblings have punctuation) +- **Capitalization after colons:** If what follows a colon is a complete sentence, capitalize the first word. *Good:* `generates two sets: The _peer_ objects that form…`. *Bad:* `generates two sets: the _peer_ objects that form…`. +- **No empty table headers:** Do not use tables with empty header cells (e.g., `| | |`) for visual separation. Every table must have meaningful column headers. If you need a key-value layout, use a definition list or a two-column table with headers like `Property` / `Value` or `Field` / `Description`. +- **Horizontal rules (`---`):** Do not insert `---` between subsections within the same heading level purely for visual spacing. Use them only to separate fundamentally different major sections (e.g., between "User-Facing Configuration" and "Infrastructure Configuration"). Markdown headings already provide visual separation. +- **Voice consistency:** Always use "you" (second person) when addressing the reader — not "users" or "the user." *Good:* `configuration that you typically interact with`. *Bad:* `configuration that users typically interact with`. +- **Avoid exposing internals unnecessarily:** Do not describe implementation details (e.g., "hidden metadata list") unless the reader needs that information to perform a task. If an internal mechanism is relevant (e.g., for import/export behavior), introduce it where it is actionable, not in overviews. - **Admonitions:** use Docusaurus syntax — `:::note`, `:::tip`, `:::caution`, `:::important`, `:::danger`. Close with `:::`. - **Code blocks:** always specify the language hint (`text`, `bash`, `yaml`, `json`, `python`). - **Avoid jargon** unless defined on first use; link to a concept page if one exists. diff --git a/docs/config_autogenerated.md b/docs/config_autogenerated.md index d297394ae9..97f4dbed13 100644 --- a/docs/config_autogenerated.md +++ b/docs/config_autogenerated.md @@ -13,7 +13,7 @@ On every commit, the system runs a three-phase cycle: 1. **Removal** — The system deletes all previously auto-generated elements so they can be rebuilt from scratch. There are two independent removal paths: - **Element-level:** All services, service-routes, peers, adjacencies, tenants, and service-policies where `generated` is set to `true` are collected and removed. - - **Metadata-level:** A hidden authority metadata list (`authority > generated`) tracks elements created by certain subsystems (plugins, DHCP server KNI, port-forwarding, software-update). All paths recorded in that list are removed, and the metadata entries are cleared. + - **Metadata-level:** An authority metadata list (`authority > generated`) tracks elements created by certain subsystems (plugins, DHCP server KNI, port-forwarding, software-update). All paths recorded in that list are removed, and the metadata entries are cleared. 2. **Generation** — Each subsystem builder runs and creates fresh elements. Before creating an element, the builder checks whether a matching element already exists with `generated` set to `false`. If it does, that element is treated as user-provisioned and generation is skipped. @@ -25,13 +25,17 @@ Not all subsystems use both removal paths. This distinction determines how to ov | Category | Subsystems | Removal Path | Override Method | |----------|-----------|-------------|-----------------| -| **Leaf-only** | Peer Topology builder, conductor services, BGP services, DHCP relay, PIM/MSDP, alarm shelving, internal tenants | Element-level (`generated` leaf) only | Set `generated` to `false` directly | -| **Leaf + metadata** | Plugin builder, DHCP server (KNI), software-update, port-forwarding | Both element-level and metadata-level | Use `override-generated true` | +| **Leaf-only** | Peer Topology builder, conductor services, BGP services, DHCP relay, PIM/MSDP, alarm shelving, internal tenants. | Element-level (`generated` leaf) only | Set `generated` to `false` directly | +| **Leaf + metadata** | Plugin builder, DHCP server (KNI), software-update, port-forwarding. | Both element-level and metadata-level | Use `override-generated true` | :::tip The PCLI automatically presents the correct command based on the element's category. Always use `override-generated` when it appears on the element. Only set `generated` to `false` directly when `override-generated` is not available (i.e., the `generated` leaf is visible instead). ::: +### How To Identify Auto-Generated Elements + +Any element that the system auto-generates carries `generated true` in the configuration. You can inspect this field in the PCLI to determine whether an element is system-managed or user-provisioned. For a complete list of all auto-generated element types and their override methods, see the [Quick Reference](#quick-reference) at the end of this page. + ## Taking Ownership of Auto-Generated Elements ### Recommended: The `create config autogenerated` Single-Commit Workflow @@ -46,12 +50,12 @@ This runs the same generation logic as `commit` but **stages the results into th **Workflow:** -1. Configure your triggers (neighborhoods, conductor-address, BGP neighbors, etc.) -2. Run `create config autogenerated` — auto-generated elements appear in the candidate -3. Enter config editing mode and navigate to elements you want to customize -4. Override those elements (see below) -5. Make your modifications -6. Commit **once** — the removal phase skips your overridden elements, and the generation phase sees them as user-provisioned +1. Configure your triggers (neighborhoods, conductor-address, BGP neighbors, etc.). +2. Run `create config autogenerated` — auto-generated elements appear in the candidate. +3. Enter config editing mode and navigate to elements you want to customize. +4. Override those elements (see below). +5. Make your modifications. +6. Commit **once** — the removal phase skips your overridden elements, and the generation phase sees them as user-provisioned. During the commit, elements with `generated` set to `false` survive the removal phase and are skipped during regeneration, preserving your customizations in a single commit. @@ -112,25 +116,25 @@ This works for adjacencies, service-routes, and services. ### User-Facing Configuration -This section covers auto-generated configuration that users typically interact with and may need to customize or override. +This section covers auto-generated configuration that you typically interact with and may need to customize or override. #### Peer Topology Builder -The Peer Topology builder automatically establishes the inter-router topology and distributes service reachability information across peer routers, enabling dynamic topology discovery and service mesh capabilities without manual configuration. It generates two related sets of elements: the _peer_ and _adjacency_ objects that form the inter-router topology, and the peer-type _service-route_ objects that distribute service reachability across that topology. +The Peer Topology builder automatically establishes the inter-router topology and distributes service reachability information across peer routers, enabling dynamic topology discovery and service mesh capabilities without manual configuration. It generates two related sets of elements: The _peer_ and _adjacency_ objects that form the inter-router topology, and the peer-type _service-route_ objects that distribute service reachability across that topology. -**Peers and adjacencies** +**Peers and Adjacencies** -| | | +| Field | Description | |---|---| -| **Trigger** | _neighborhood_ configured on a forwarding _network-interface_ | -| **What is generated** | _peer_ objects between routers sharing the same neighborhood; _adjacency_ objects on both sides | +| **Trigger** | _neighborhood_ configured on a forwarding _network-interface_. | +| **What is generated** | _peer_ objects between routers sharing the same neighborhood; _adjacency_ objects on both sides. | | **Category** | Leaf-only | Conditions for generation: -- The _network-interface_ must have `forwarding` set to `true` (default) and at least one _neighborhood_ entry -- Topology matching: `mesh` ↔ `mesh`/`hub`/`spoke`; `hub` ↔ `spoke`/`mesh`; `spoke` ↔ `hub`/`mesh` -- `peer-connectivity` must not be `outbound-only` on **both** sides -- `inter-router-security` must be set on any interface with a neighborhood +- The _network-interface_ must have `forwarding` set to `true` (default) and at least one _neighborhood_ entry. +- Topology matching: `mesh` ↔ `mesh`/`hub`/`spoke`; `hub` ↔ `spoke`/`mesh`; `spoke` ↔ `hub`/`mesh`. +- `peer-connectivity` must not be `outbound-only` on **both** sides. +- `inter-router-security` must be set on any interface with a neighborhood. | Method | Scope | Effect | |--------|-------|--------| @@ -145,18 +149,18 @@ There is no global toggle. If neighborhoods are configured, peers and adjacencie **Service-routes** -| | | +| Field | Description | |---|---| -| **Trigger** | A router has a non-peer _service-route_ for a shared service, and peer routers exist | -| **What is generated** | Peer-type _service-route_ objects on remote routers pointing back to the source | +| **Trigger** | A router has a non-peer _service-route_ for a shared service, and peer routers exist. | +| **What is generated** | Peer-type _service-route_ objects on remote routers pointing back to the source. | | **Category** | Leaf-only | Conditions for generation: -1. Service has `share-service-routes` set to `true` (default) -2. Source router has at least one non-peer service-route (e.g., next-hop) for the service -3. Service `application-type` is `generic` -4. Service `applies-to` allows the peer router -5. Authority is not using a Peer Topology repository +1. Service has `share-service-routes` set to `true` (default). +2. Source router has at least one non-peer service-route (e.g., next-hop) for the service. +3. Service `application-type` is `generic`. +4. Service `applies-to` allows the peer router. +5. Authority is not using a Peer Topology repository. | Method | Scope | Effect | |--------|-------|--------| @@ -165,16 +169,15 @@ Conditions for generation: | Set `generated` to `false` on a service-route | Per-element | Takes ownership of that route | | Pre-provision a service-route with the same name | Per-element | System skips generation for that route | ---- #### Conductor Services The Conductor Services subsystem provides automatic connectivity from managed routers back to the conductor system, enabling centralized configuration, monitoring, and software updates. Generation is unconditional when any `conductor-address` is configured. There is no way to fully disable this category, but there are customization options and per-element overrides: -| | | +| Field | Description | |---|---| -| **Trigger** | `conductor-address` is configured on the authority | -| **What is generated** | Conductor reachability _service_, _service-policy_, _service-route_, and related _tenant_ objects | +| **Trigger** | `conductor-address` is configured on the authority. | +| **What is generated** | Conductor reachability _service_, _service-policy_, _service-route_, and related _tenant_ objects. | | **Category** | Leaf-only | | Method | Level | Effect | @@ -184,16 +187,15 @@ The Conductor Services subsystem provides automatic connectivity from managed ro | `management-service-generation > proxy` | Router only | Enable/disable proxy of public-to-private conductor addresses | | Set `generated` to `false` on a conductor service or route | Per-element | Takes ownership of that element | ---- #### Management Over Forwarding Interface (MOFI) Services The MOFI builder automatically provisions management services for various network management and operational functions, enabling these services to be delivered over forwarding interfaces (data plane) when management interfaces are not available. This provides management connectivity through active data paths. -| | | +| Field | Description | |---|---| -| **Trigger** | A _network-interface_ configured with `management: true` on a forwarding interface | -| **What is generated** | Services and service-routes for NTP, DNS, SNMP, Syslog, IPFIX, HTTP-HTTPS (package updates), and Audit functions | +| **Trigger** | A _network-interface_ configured with `management: true` on a forwarding interface. | +| **What is generated** | Services and service-routes for NTP, DNS, SNMP, Syslog, IPFIX, HTTP-HTTPS (package updates), and Audit functions. | | **Category** | Leaf-only | The builder generates services for the following management traffic types: @@ -218,13 +220,12 @@ The builder generates services for the following management traffic types: MOFI services are generated with the lowest priority to ensure they don't override user-configured services with the same names. Pre-provisioning a service with the same name before generation will prevent the auto-generated version from being created. ::: ---- #### BGP Services and Service-Routes The BGP subsystem automatically establishes reachability to BGP peers, enabling dynamic routing protocol operation and network convergence without manual service definition. -| | | +| Field | Description | |---|---| | **Trigger** | BGP neighbor transport configuration | | **What is generated** | BGP peering _service_ and _service-route_ objects for BGP neighbor reachability | @@ -238,15 +239,14 @@ The BGP subsystem automatically establishes reachability to BGP peers, enabling | Set `bgp-service-generation > route-reflector-client-mesh` | Authority | Generate service-route mesh for route reflector clients | | Set `generated` to `false` on a BGP service | Per-element | Takes ownership of that service | -BGP service generation is **fully disableable** per-neighbor using the `disabled` option. +You can fully disable BGP service generation on a per-neighbor basis using the `disabled` option. ---- #### DHCP Server KNI Device-Interfaces The DHCP server subsystem automatically provisions kernel network interfaces required for DHCP server operation, handling the internal networking plumbing transparently. -| | | +| Field | Description | |---|---| | **Trigger** | `host-service` of type `dhcp-server` configured on a _network-interface_ | | **What is generated** | KNI _device-interface_ objects for DHCP server operation | @@ -254,18 +254,17 @@ The DHCP server subsystem automatically provisions kernel network interfaces req | Setting | Level | Effect | |---------|-------|--------| -| `dhcp-server-generated-address-pool` | Authority (`application-identification`) | Changes the address pool for generated KNI interfaces (default: `169.254.130.0/24`) | -| `override-generated true` on the KNI interface | Per-element | Takes ownership of that element | +| `dhcp-server-generated-address-pool` | Authority (`application-identification`) | Changes the address pool for generated KNI interfaces (default: `169.254.130.0/24`). | +| `override-generated true` on the KNI interface | Per-element | Takes ownership of that element. | There is no flag to fully disable DHCP KNI generation. Remove the `dhcp-server` host-service to prevent generation. ---- #### DHCP Relay Services and Routes The DHCP relay subsystem automatically provisions the DHCP relay service and reachability paths to DHCP servers, enabling DHCP client support on networks without a local DHCP server. -| | | +| Field | Description | |---|---| | **Trigger** | DHCP relay agent configured on a _network-interface_ | | **What is generated** | DHCP relay _service_ and _service-route_ objects | @@ -276,13 +275,12 @@ The DHCP relay subsystem automatically provisions the DHCP relay service and rea | Remove DHCP relay configuration | Per-interface | Prevents generation | | Set `generated` to `false` on the service or route | Per-element | Takes ownership of that element | ---- #### Application Identification (App-ID) Services The App-ID subsystem automatically creates granular service categories for application identification, allowing fine-grained traffic classification and policy enforcement without manual service creation. -| | | +| Field | Description | |---|---| | **Trigger** | `generate-categories` set to `true` on a _service_ | | **What is generated** | Category-based child _service_ objects under the parent service | @@ -295,13 +293,12 @@ The App-ID subsystem automatically creates granular service categories for appli The default is `false` (disabled). Category services are only generated when explicitly opted-in. ---- #### PIM Multicast Services and Routes The PIM subsystem automatically establishes reachability for Protocol Independent Multicast (PIM) control traffic, enabling multicast routing operation across the network. -| | | +| Field | Description | |---|---| | **Trigger** | PIM routing configured on a router | | **What is generated** | PIM multicast _service_ and _service-route_ objects | @@ -309,13 +306,12 @@ The PIM subsystem automatically establishes reachability for Protocol Independen No independent disable flag. Remove the PIM configuration to prevent generation. Set `generated` to `false` per-element to take ownership. ---- #### MSDP Services and Routes The MSDP subsystem automatically provisions Multicast Source Discovery Protocol (MSDP) peering connectivity, enabling inter-domain multicast source discovery and reachability. -| | | +| Field | Description | |---|---| | **Trigger** | MSDP routing configured | | **What is generated** | MSDP peering _service_ and _service-route_ objects | @@ -323,17 +319,16 @@ The MSDP subsystem automatically provisions Multicast Source Discovery Protocol No independent disable flag. Remove the MSDP configuration to prevent generation. Set `generated` to `false` per-element to take ownership. ---- #### Plugin-Generated Elements Plugins extend the platform by automatically generating plugin-specific services, routes, and configuration elements as needed. -| | | +| Field | Description | |---|---| -| **Trigger** | Varies by plugin | -| **What is generated** | Plugin-specific services, routes, and other configuration | -| **Category** | Leaf + metadata | +| **Trigger** | Varies by plugin. | +| **What is generated** | Plugin-specific services, routes, and other configuration. | +| **Category** | Leaf + metadata. | Use `override-generated true` on any plugin-generated element to take ownership. @@ -347,13 +342,12 @@ This section covers auto-generated configuration managed by the platform for int The software update subsystem automatically configures internal proxy settings for software updates on managed routers, ensuring seamless update delivery without manual configuration. This is a hidden, internally managed setting. It is unconditionally set when managed routers exist. There is no opt-out mechanism and no override is available. ---- #### Secure Conductor Onboarding (SCO) The SCO subsystem automatically manages the secure onboarding mode for routers and configures pre-shared keys (PSK) required for secure conductor communication. This enables secure, automated onboarding of managed routers without manual key management. -| | | +| Field | Description | |---|---| | **Trigger** | Routers with `system/secure-conductor-onboarding/mode` configured | | **What is generated** | SCO operating mode (EXCLUSIVE or DISABLED) and pre-shared keys for routers | @@ -368,24 +362,23 @@ The SCO subsystem automatically manages the secure onboarding mode for routers a SCO operates at the system level and is automatically managed based on the configured operating mode. PSKs are only generated when SCO is enabled and are required for the conductor to authenticate the router. ::: ---- #### Resource Groups The Resource Groups subsystem automatically associates configuration resources (routers, services, tenants, security profiles, etc.) with role-based access control (RBAC) resource groups. This enables policy enforcement for resource group-scoped access controls without manual resource enumeration. -| | | +| Field | Description | |---|---| -| **Trigger** | Configuration resources exist in the authority; roles define resource groups | -| **What is generated** | Resource entries in roles linking to configuration objects | +| **Trigger** | Configuration resources exist in the authority; roles define resource groups. | +| **What is generated** | Resource entries in roles linking to configuration objects. | | **Category** | Leaf-only | Supported resource types include: -- Network elements (routers, districts) -- Services and traffic policies (services, service-classes, traffic-profiles) -- Security and access (tenants, security profiles, LDAP servers) -- Operational configuration (alarm shelves, performance profiles, DSCP maps, IPFIX collectors) -- Extensibility (STEP repos, PCLI aliases, session-types) +- Network elements (routers, districts). +- Services and traffic policies (services, service-classes, traffic-profiles). +- Security and access (tenants, security profiles, LDAP servers). +- Operational configuration (alarm shelves, performance profiles, DSCP maps, IPFIX collectors). +- Extensibility (STEP repos, PCLI aliases, session-types). | Method | Scope | Effect | |--------|-------|--------| @@ -396,13 +389,12 @@ Supported resource types include: Resource groups are generated with lowest priority; user-provisioned resources with matching names prevent auto-generation. This enables administrators to define custom resource mappings when needed. ::: ---- #### Alarm Shelving The alarm shelving subsystem automatically manages alarm suppression (shelving) based on internal platform logic, suppressing non-critical alarms during expected operational conditions. -| | | +| Field | Description | |---|---| | **Trigger** | Internal alarm shelving logic | | **What is generated** | Alarm shelf entries | @@ -410,23 +402,21 @@ The alarm shelving subsystem automatically manages alarm suppression (shelving) Set `generated` to `false` per-element to take ownership. ---- #### Internal Tenants The platform automatically provisions internal logical containers (tenants) for services and features that require tenant isolation without burdening users with these internal details. -| | | +| Field | Description | |---|---| -| **Trigger** | Conductor services, BGP, or other internal features are active | -| **What is generated** | Internal tenants such as `_internal_`, `_bgp_speaker_` | +| **Trigger** | Conductor services, BGP, or other internal features are active. | +| **What is generated** | Internal tenants such as `_internal_`, `_bgp_speaker_`. | | **Category** | Leaf-only | :::warning These tenants are required for the platform to function. Setting `generated` to `false` is technically possible but **not recommended** — it may impact platform functionality. ::: ---- #### Auto-Generated IDs @@ -454,18 +444,18 @@ A hidden list at `authority > generated` tracks elements created by certain subs | State | Removed? | Regenerated? | Assessment | |-------|:--------:|:------------:|------------| -| `generated true`, no metadata | Yes (leaf) | Yes | Normal leaf-only behavior | -| `generated false`, no metadata | No | No | **Safe** — fully protected | -| `generated true`, metadata `persistent false` | Yes (both paths) | Yes | Normal metadata-tracked behavior | -| `generated false`, metadata `persistent false` | Yes (metadata) | May be | **Unsafe** — metadata removal still deletes it | -| `generated false`, metadata `persistent true` | No | No | **Safe** — what `override-generated true` sets | -| `generated true`, metadata `persistent true` | Yes (leaf) | Yes | **Unsafe** — leaf removal still deletes it | +| `generated true`, no metadata. | Yes (leaf) | Yes | Normal leaf-only behavior | +| `generated false`, no metadata. | No | No | **Safe** — fully protected | +| `generated true`, metadata `persistent false`. | Yes (both paths) | Yes | Normal metadata-tracked behavior | +| `generated false`, metadata `persistent false`. | Yes (metadata) | May be | **Unsafe** — metadata removal still deletes it | +| `generated false`, metadata `persistent true`. | No | No | **Safe** — what `override-generated true` sets | +| `generated true`, metadata `persistent true`. | Yes (leaf) | Yes | **Unsafe** — leaf removal still deletes it | ### PCLI Visibility The `generated` leaf and `override-generated` command are mutually exclusive in the PCLI: -- If a metadata entry exists → `generated` leaf is hidden; `override-generated` is shown -- If no metadata entry exists → `generated` leaf is visible; `override-generated` is hidden +- If a metadata entry exists → `generated` leaf is hidden; `override-generated` is shown. +- If no metadata entry exists → `generated` leaf is visible; `override-generated` is hidden. ## Import/Export Behavior @@ -474,11 +464,11 @@ The `export config` and `import config` PCLI commands save and restore the full Both the `generated` leaf on individual elements **and** the `authority > generated` metadata list are **fully preserved** during export and import. The export serializes the entire configuration tree without filtering. This means: -- All auto-generated elements, their `generated` boolean values, and any `override-generated` state survive a round-trip export/import -- The `authority > generated` metadata entries (including `persistent` flags) are included -- The configuration behaves identically after import — the same PCLI commands are available, and the same override protections are in effect -- Elements with `generated true` will still be removed and re-generated on the next commit after import -- Elements previously overridden (`generated false` or `persistent true`) remain protected +- All auto-generated elements, their `generated` boolean values, and any `override-generated` state survive a round-trip export/import. +- The `authority > generated` metadata entries (including `persistent` flags) are included. +- The configuration behaves identically after import — the same PCLI commands are available, and the same override protections are in effect. +- Elements with `generated true` will still be removed and re-generated on the next commit after import. +- Elements previously overridden (`generated false` or `persistent true`) remain protected. ## Quick Reference @@ -486,14 +476,14 @@ This means: | Element | Dedicated Disable Option | Per-Element Override | |---------|-------------------------|---------------------| -| Peer Topology builder service-routes | `share-service-routes false` | `generated false` | -| Peer Topology builder peers/adjacencies | Remove _neighborhood_ | `generated false` | +| Peer Topology builder service-routes. | `share-service-routes false` | `generated false` | +| Peer Topology builder peers/adjacencies. | Remove _neighborhood_ | `generated false` | | Conductor services | No (customization knobs only) | `generated false` | -| MOFI services (NTP, DNS, SNMP, etc.) | Remove `management: true` from interface | `generated false` | +| MOFI services (NTP, DNS, SNMP, etc.). | Remove `management: true` from interface | `generated false` | | BGP services | `bgp-service-generation > disabled` | `generated false` | -| DHCP relay services | Remove relay config | `generated false` | -| DHCP server KNI interfaces | Remove `dhcp-server` host-service | `override-generated true` | -| App-ID category services | `generate-categories false` (default) | `generated false` | +| DHCP relay services. | Remove relay config | `generated false` | +| DHCP server KNI interfaces. | Remove `dhcp-server` host-service | `override-generated true` | +| App-ID category services. | `generate-categories false` (default) | `generated false` | | PIM/MSDP services | Remove routing config | `generated false` | | Plugin-generated elements | Varies by plugin | `override-generated true` | From 9c4d0e6518231230b750997a76484f3285080518 Mon Sep 17 00:00:00 2001 From: Kaushik Agrawal Date: Mon, 18 May 2026 12:06:06 -0400 Subject: [PATCH 10/10] address remaining comments --- docs/config_autogenerated.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config_autogenerated.md b/docs/config_autogenerated.md index 97f4dbed13..811aeea427 100644 --- a/docs/config_autogenerated.md +++ b/docs/config_autogenerated.md @@ -60,7 +60,7 @@ This runs the same generation logic as `commit` but **stages the results into th During the commit, elements with `generated` set to `false` survive the removal phase and are skipped during regeneration, preserving your customizations in a single commit. :::note -If the underlying trigger configuration changes (e.g., new neighborhoods, new conductor addresses), re-run `create config autogenerated` to preview newly generated elements before committing. +If the underlying changes (e.g., new neighborhoods, new conductor addresses) trigger configuration updates, re-run `create config autogenerated` to preview newly generated elements before committing. ::: ### Overriding Leaf-Only Elements