Skip to content

docs: adopt canonical device names across documentation#8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jmgilman merged 1 commit into from
Aug 15, 2026
Merged

docs: adopt canonical device names across documentation #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 47 additions & 47 deletions docs/docs/designs/drafts/lab-v2-core-network.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -13,12 +13,13 @@ related-decisions:

## Summary

The core network uses a Minisforum VP6630 running VyOS for Layer 3 routing,
firewall policy, and NAT. A MikroTik CRS309-1G-8S+IN handles core Layer 2
switching and VLAN transport. A TRENDnet TEG-3102WS connects both non-SFP NICs
from each MS-02 to the VP6630 for management/OOB traffic. A second MikroTik
CRS309-1G-8S+IN acts as the home router and connects the lab to the home
network and the internet.
The core network uses `gw01`, a Minisforum VP6630 running VyOS, for Layer 3
routing, firewall policy, and NAT. `sw-core01`, a MikroTik CRS309-1G-8S+IN,
handles core Layer 2 switching and VLAN transport. `sw-mgmt01`, a TRENDnet
TEG-3102WS, connects both non-SFP NICs from each MS-02 node to `gw01` for
management/OOB traffic. `rtr01`, a second MikroTik CRS309-1G-8S+IN, acts as the
home router and connects the lab to the home network and the internet. Device
names are canonical per the [naming registry](../../reference/naming.md).

This design defines device responsibilities, logical topology, configuration
requirements, failure boundaries, and verification criteria. Address
Expand All@@ -27,11 +28,11 @@ ownership are outside this document.

## Goals

- Keep routing and traffic policy on VyOS.
- Keep core VLAN transport and physical switching on the core CRS309-1G-8S+IN.
- Carry MS-02 management/OOB traffic through the TEG-3102WS.
- Keep routing and traffic policy on `gw01`.
- Keep core VLAN transport and physical switching on `sw-core01`.
- Carry MS-02 management/OOB traffic through `sw-mgmt01`.
- Route home-to-lab traffic without source NAT.
- Apply source NAT to lab-to-internet traffic on VyOS.
- Apply source NAT to lab-to-internet traffic on `gw01`.
- Store network-device configuration in version control.
- Validate behavior before saving a deployed configuration.
- Preserve a recovery path that does not depend on the primary network path.
Expand All@@ -52,30 +53,30 @@ ownership are outside this document.

```mermaid
flowchart LR
HOME[Home network] --> RTR[Home router CRS309-1G-8S+IN]
RTR -->|Routed transit| VYOS[VP6630 running VyOS]
VYOS -->|802.1Q trunk| CRS[Core CRS309-1G-8S+IN]
HOME[Home network] --> RTR[rtr01 home router]
RTR -->|Routed transit| VYOS[gw01 VyOS gateway]
VYOS -->|802.1Q trunk| CRS[sw-core01 core switch]
CRS --> SEGMENTS[Lab network segments]
VYOS -->|Management/OOB uplink| TEG[TEG-3102WS]
TEG -->|Two non-SFP NICs per node| MS02[MS-02 nodes]
VYOS -->|Management/OOB uplink| TEG[sw-mgmt01]
TEG -->|Two non-SFP NICs per node| MS02[lab01, lab02, lab03]
```

The home router routes traffic between the home network and the VyOS transit
interface. VyOS routes lab prefixes, applies firewall policy, and performs
source NAT for internet egress. The core CRS309-1G-8S+IN carries lab VLANs between
VyOS and connected lab devices. The TEG-3102WS connects directly to the VP6630
and carries management/OOB traffic for both non-SFP NICs on each MS-02.
`rtr01` routes traffic between the home network and the `gw01` transit
interface. `gw01` routes lab prefixes, applies firewall policy, and performs
source NAT for internet egress. `sw-core01` carries lab VLANs between `gw01`
and connected lab devices. `sw-mgmt01` connects directly to `gw01` and carries
management/OOB traffic for both non-SFP NICs on each MS-02 node.
The [physical connection map](../../reference/networking/physical-connections.md) is the
authoritative port-to-port cabling record.

## Device Responsibilities

| Device | Responsibilities |
| --- | --- |
| MikroTik CRS309-1G-8S+IN (home router) | Home-network routing, internet access, and the upstream side of the routed lab transit |
| Minisforum VP6630 running VyOS | Lab gateways, route selection, firewall policy, source NAT, the downstream side of the routed transit, and the management/OOB gateway |
| MikroTik CRS309-1G-8S+IN (core switch) | Core VLAN transport, access ports, trunks, and physical link aggregation |
| TRENDnet TEG-3102WS | Layer 2 management/OOB connectivity for both non-SFP NICs on each MS-02 and a direct uplink to the VP6630 |
| `rtr01` (MikroTik CRS309-1G-8S+IN) | Home-network routing, internet access, and the upstream side of the routed lab transit |
| `gw01` (Minisforum VP6630 running VyOS) | Lab gateways, route selection, firewall policy, source NAT, the downstream side of the routed transit, and the management/OOB gateway |
| `sw-core01` (MikroTik CRS309-1G-8S+IN) | Core VLAN transport, access ports, trunks, and physical link aggregation |
| `sw-mgmt01` (TRENDnet TEG-3102WS) | Layer 2 management/OOB connectivity for both non-SFP NICs on each MS-02 and a direct uplink to `gw01` |

[ADR-0001](../../decisions/0001-use-vyos-for-layer-3-and-switches-for-layer-2.md)
defines the Layer 2 and Layer 3 boundary.
Expand All@@ -84,24 +85,24 @@ defines the Layer 2 and Layer 3 boundary.

The routing design has these invariants:

- The home router has routes for lab prefixes through the VyOS transit address.
- VyOS uses the home router's transit address as its default route.
- VyOS owns the gateway address for every routed lab segment.
- The core CRS309-1G-8S+IN and TEG-3102WS do not route between lab segments.
- `rtr01` has routes for lab prefixes through the `gw01` transit address.
- `gw01` uses the `rtr01` transit address as its default route.
- `gw01` owns the gateway address for every routed lab segment.
- `sw-core01` and `sw-mgmt01` do not route between lab segments.
- Home-to-lab traffic retains its original source address.
- VyOS applies source NAT to lab-to-internet traffic.
- `gw01` applies source NAT to lab-to-internet traffic.
- Firewall rules distinguish new connections from established reply traffic.

## Traffic Policy

VyOS enforces policy for:
`gw01` enforces policy for:

- Home network to lab segments
- Lab segments to the home network
- Lab segments to the internet
- Traffic between routed lab segments
- Traffic addressed to VyOS
- Management/OOB traffic through the TEG-3102WS
- Traffic addressed to `gw01`
- Management/OOB traffic through `sw-mgmt01`
- Management traffic addressed to network devices

Each firewall rule identifies the source, destination, protocol, destination
Expand All@@ -111,8 +112,8 @@ the reverse direction.

## Configuration Requirements

VyOS and both switches each have one version-controlled configuration source.
The deployment process:
`gw01`, `sw-core01`, and `sw-mgmt01` each have one version-controlled
configuration source. The deployment process:

1. Renders the effective configuration.
2. Validates syntax and policy before deployment.
Expand All@@ -127,8 +128,8 @@ Drift detection compares each running configuration with its repository source.
## Management and Recovery

Firewall policy limits routine management access to approved source networks.
The TEG-3102WS carries management/OOB traffic from both non-SFP NICs on each
MS-02 directly to the VP6630.
`sw-mgmt01` carries management/OOB traffic from both non-SFP NICs on each
MS-02 node directly to `gw01`.

Each network device has a recovery path that remains available when its
production configuration or primary network link fails. Recovery credentials do
Expand All@@ -138,12 +139,12 @@ not reside in device configuration committed to the repository.

| Failure | Effect |
| --- | --- |
| Home router failure | The lab loses home-network and internet connectivity. Internal lab switching and routing remain available. |
| VP6630 or VyOS failure | Routed lab segments lose their gateways, inter-segment routing, policy enforcement, management/OOB gateway, and internet egress. |
| Core switch failure | Devices connected through the core switch lose Layer 2 connectivity. |
| TEG-3102WS or its VP6630 uplink failure | Both non-SFP NICs on each MS-02 lose management/OOB connectivity. |
| `rtr01` failure | The lab loses home-network and internet connectivity. Internal lab switching and routing remain available. |
| `gw01` failure | Routed lab segments lose their gateways, inter-segment routing, policy enforcement, management/OOB gateway, and internet egress. |
| `sw-core01` failure | Devices connected through `sw-core01` lose Layer 2 connectivity. |
| `sw-mgmt01` or its `gw01` uplink failure | Both non-SFP NICs on each MS-02 lose management/OOB connectivity. |
| Routed transit failure | Home-to-lab and lab-to-internet traffic stop. Internal lab traffic remains available within its unaffected Layer 2 and Layer 3 paths. |
| VyOS-to-core-switch trunk failure | VLANs carried by the trunk lose their VyOS gateways. |
| `gw01`-to-`sw-core01` trunk failure | VLANs carried by the trunk lose their `gw01` gateways. |
| Invalid configuration | Deployment verification fails and the previous configuration is restored. |

## Verification
Expand All@@ -152,15 +153,14 @@ A deployment is valid when the observed behavior matches these checks:

- Every connected interface reports the assigned link state and speed.
- Each VLAN is present only on its assigned access ports and trunks.
- A client in each routed segment reaches its VyOS gateway.
- The home router and VyOS route tables contain the required transit and lab routes.
- A client in each routed segment reaches its `gw01` gateway.
- The `rtr01` and `gw01` route tables contain the required transit and lab routes.
- Home-to-lab traffic retains its home-network source address.
- Lab-to-internet traffic uses the VyOS source-NAT address.
- Lab-to-internet traffic uses the `gw01` source-NAT address.
- Each permitted firewall flow succeeds.
- Each denied firewall flow fails.
- Established reply traffic succeeds without enabling a new reverse flow.
- Both non-SFP NICs on each MS-02 connect through the TEG-3102WS.
- MS-02 management/OOB traffic reaches the VP6630 through the TEG-3102WS
uplink.
- Both non-SFP NICs on each MS-02 connect through `sw-mgmt01`.
- MS-02 management/OOB traffic reaches `gw01` through the `sw-mgmt01` uplink.
- Management access succeeds only from approved source networks.
- A failed deployment restores the previous configuration.
2 changes: 2 additions & 0 deletions docs/docs/index.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -23,6 +23,8 @@ and runbook lives here.

## Reference

- [Device naming](reference/naming.md) is the canonical registry of device
names and the rules for assigning them.
- [Hardware inventory](reference/hardware-inventory.md) records every physical
device in the lab with its model and specifications.
- [Networking hardware](reference/networking/hardware.md) identifies the core
Expand Down
3 changes: 2 additions & 1 deletion docs/docs/reference/hardware-inventory.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -8,7 +8,8 @@ description: Physical inventory of lab equipment with models, quantities, and sp
This document is the physical inventory of lab equipment. It records models,
quantities, product references, and concrete specifications.

Role assignments for core network devices live in the
Canonical device names live in the [naming registry](naming.md). Role
assignments for core network devices live in the
[networking hardware reference](networking/hardware.md). Installed cabling
lives in the [physical connection map](networking/physical-connections.md).
IP addressing, VLANs, and other network configuration belong to the network
Expand Down
51 changes: 51 additions & 0 deletions docs/docs/reference/naming.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
---
title: Device Naming
description: Canonical device names and the rules for assigning them.
---

# Device Naming

Every commissioned device has exactly one canonical name. The canonical name
is:

- the device's configured system identity (hostname, RouterOS identity, or
web-UI system name),
- the physical label on the chassis, and
- the only device identifier used in documentation and configuration.

## Rules

- Names are lowercase DNS-safe labels: `a-z`, `0-9`, and `-`.
- Names are role-based with a zero-padded two-digit ordinal, for example
`gw01`.
- Uncommissioned hardware has no name. The
[hardware inventory](hardware-inventory.md) refers to it by model. A name is
assigned when the device is commissioned.
- Repurposing a device renames it. Update this registry, the device's system
identity, its chassis label, and every document that references the old
name in the same unit of work.

## Registry

| Name | Device | Role |
| --- | --- | --- |
| `gw01` | Protectli VP6630 | Lab gateway running VyOS |
| `rtr01` | MikroTik CRS309-1G-8S+IN (unit 1) | Home router and internet edge |
| `sw-core01` | MikroTik CRS309-1G-8S+IN (unit 2) | Core Layer 2 switch |
| `sw-mgmt01` | TRENDnet TEG-3102WS | Management/OOB switch |
| `lab01` | Minisforum MS-02 Ultra (unit 1) | Compute node |
| `lab02` | Minisforum MS-02 Ultra (unit 2) | Compute node |
| `lab03` | Minisforum MS-02 Ultra (unit 3) | Compute node |
| `nas01` | Minisforum N5 Pro | NAS |
| `pikvm01` | PiKVM V4 Plus | KVM-over-IP console |
| `kvm01` | TESmart HKS801-EB23 8x1 KVM | Console switch |
| `ups01` | APC Smart-UPS SMT1000 | UPS |

## Unnamed hardware

| Device | Status |
| --- | --- |
| Minisforum UM760 | Shelf spare; named at commissioning |

Models and physical specifications live in the
[hardware inventory](hardware-inventory.md).
14 changes: 8 additions & 6 deletions docs/docs/reference/networking/hardware.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -5,19 +5,21 @@ description: Core network devices and their assigned roles.

# Hardware

Device names are canonical per the [naming registry](../naming.md).

## Core devices

| Component | Platform | Role |
| Device | Platform | Role |
| --- | --- | --- |
| Lab gateway | Minisforum VP6630 running VyOS | Routes lab networks, enforces firewall policy, and performs source NAT |
| Core switch | MikroTik `CRS309-1G-8S+IN` | Carries lab VLANs and connects lab devices at Layer 2 |
| Management/OOB switch | TRENDnet `TEG-3102WS` | Connects both non-SFP NICs from each MS-02 for management/OOB traffic |
| `gw01` | Protectli VP6630 running VyOS | Routes lab networks, enforces firewall policy, and performs source NAT |
| `sw-core01` | MikroTik `CRS309-1G-8S+IN` | Carries lab VLANs and connects lab devices at Layer 2 |
| `sw-mgmt01` | TRENDnet `TEG-3102WS` | Connects both non-SFP NICs from each MS-02 for management/OOB traffic |

## External dependency

| Component | Platform | Role |
| Device | Platform | Role |
| --- | --- | --- |
| Home router | MikroTik `CRS309-1G-8S+IN` (second unit of the core-switch model) | Routes the home network, provides internet access, and terminates the upstream side of the routed lab transit |
| `rtr01` | MikroTik `CRS309-1G-8S+IN` | Routes the home network, provides internet access, and terminates the upstream side of the routed lab transit |

Models and physical specifications live in the
[hardware inventory](../hardware-inventory.md). The
Expand Down
46 changes: 23 additions & 23 deletions docs/docs/reference/networking/physical-connections.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -5,42 +5,42 @@ description: Authoritative port-to-port map of the installed network cabling.

# Physical Connections

Each row records one installed cable. Port names match the labels on the device
Each row records one installed cable. Device names are canonical per the
[naming registry](../naming.md). Port names match the labels on the device
chassis. `Unlabeled Ethernet port` identifies a physical Ethernet port that has
no printed label. Two MikroTik CRS309-1G-8S+IN units are installed; rows
qualify them by role as `(home router)` and `(core switch)`.
no printed label.

## Connected ports

| Connection | Device A | Port A | Device B | Port B |
| --- | --- | --- | --- | --- |
| `PHY-001` | MikroTik CRS309-1G-8S+IN (home router) | `SFP+ 1` | Minisforum VP6630 | `SFP+ 1` |
| `PHY-002` | Minisforum VP6630 | `SFP+ 2` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 8` |
| `PHY-003` | Minisforum VP6630 | `Port 2` | TRENDnet TEG-3102WS | `Port 1` |
| `PHY-004` | Minisforum VP6630 | `Port 3` | PiKVM | `Unlabeled Ethernet port` |
| `PHY-005` | Minisforum VP6630 | `Port 4` | TESmart 8x1 KVM | `Unlabeled Ethernet port` |
| `PHY-006` | TRENDnet TEG-3102WS | `Port 2` | LAB01 | `Top Port` |
| `PHY-007` | TRENDnet TEG-3102WS | `Port 3` | LAB01 | `Bottom Port` |
| `PHY-008` | TRENDnet TEG-3102WS | `Port 4` | LAB02 | `Top Port` |
| `PHY-009` | TRENDnet TEG-3102WS | `Port 5` | LAB02 | `Bottom Port` |
| `PHY-010` | TRENDnet TEG-3102WS | `Port 6` | LAB03 | `Top Port` |
| `PHY-011` | TRENDnet TEG-3102WS | `Port 7` | LAB03 | `Bottom Port` |
| `PHY-012` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 1` | LAB01 | `Right SFP 25G` |
| `PHY-013` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 2` | LAB01 | `Left SFP 25G` |
| `PHY-014` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 3` | LAB02 | `Right SFP 25G` |
| `PHY-015` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 4` | LAB02 | `Left SFP 25G` |
| `PHY-016` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 5` | LAB03 | `Right SFP 25G` |
| `PHY-017` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 6` | LAB03 | `Left SFP 25G` |
| `PHY-018` | MikroTik CRS309-1G-8S+IN (core switch) | `Port 7` | NAS | `10GB Port` |
| `PHY-001` | `rtr01` | `SFP+ 1` | `gw01` | `SFP+ 1` |
| `PHY-002` | `gw01` | `SFP+ 2` | `sw-core01` | `Port 8` |
| `PHY-003` | `gw01` | `Port 2` | `sw-mgmt01` | `Port 1` |
| `PHY-004` | `gw01` | `Port 3` | `pikvm01` | `Unlabeled Ethernet port` |
| `PHY-005` | `gw01` | `Port 4` | `kvm01` | `Unlabeled Ethernet port` |
| `PHY-006` | `sw-mgmt01` | `Port 2` | `lab01` | `Top Port` |
| `PHY-007` | `sw-mgmt01` | `Port 3` | `lab01` | `Bottom Port` |
| `PHY-008` | `sw-mgmt01` | `Port 4` | `lab02` | `Top Port` |
| `PHY-009` | `sw-mgmt01` | `Port 5` | `lab02` | `Bottom Port` |
| `PHY-010` | `sw-mgmt01` | `Port 6` | `lab03` | `Top Port` |
| `PHY-011` | `sw-mgmt01` | `Port 7` | `lab03` | `Bottom Port` |
| `PHY-012` | `sw-core01` | `Port 1` | `lab01` | `Right SFP 25G` |
| `PHY-013` | `sw-core01` | `Port 2` | `lab01` | `Left SFP 25G` |
| `PHY-014` | `sw-core01` | `Port 3` | `lab02` | `Right SFP 25G` |
| `PHY-015` | `sw-core01` | `Port 4` | `lab02` | `Left SFP 25G` |
| `PHY-016` | `sw-core01` | `Port 5` | `lab03` | `Right SFP 25G` |
| `PHY-017` | `sw-core01` | `Port 6` | `lab03` | `Left SFP 25G` |
| `PHY-018` | `sw-core01` | `Port 7` | `nas01` | `10GB Port` |
| `PHY-019` | `sw-mgmt01` | `Port 8` | `nas01` | `5GB Port` |

## Unconnected ports

Only ports explicitly identified as unconnected are listed.

| Device | Port |
| --- | --- |
| Minisforum VP6630 | `Port 1` |
| TRENDnet TEG-3102WS | `Port 8` |
| `gw01` | `Port 1` |

IP addresses, VLANs, bonds, interface names, and link settings belong to the
network configuration rather than this physical map.
1 change: 1 addition & 0 deletions docs/mkdocs.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -37,6 +37,7 @@ nav:
- Drafts:
- Lab v2 core network: designs/drafts/lab-v2-core-network.md
- Reference:
- Device naming: reference/naming.md
- Hardware inventory: reference/hardware-inventory.md
- Networking:
- Hardware: reference/networking/hardware.md
Expand Down