From 6c58671d15ccf24d23b3265d322c20efd24bc445 Mon Sep 17 00:00:00 2001 From: reachableceo Date: Thu, 6 Aug 2026 11:25:19 -0500 Subject: [PATCH] docs: add Redmine ticket references to subsystem READMEs Each component README now links to its corresponding Redmine tickets (closed for completed work, open for pending items) for bidirectional traceability between code and system of record. --- awx/README.md | 2 + dcinfra/console/README.md | 260 ++++++++++++++------------- dcinfra/powerman/README.md | 2 + dcinfra/ups/README.md | 2 + k8s/README.md | 2 + netinfra/dns-cluster-setup/README.md | 2 + 6 files changed, 141 insertions(+), 129 deletions(-) diff --git a/awx/README.md b/awx/README.md index 1c791c7..e4d83b5 100644 --- a/awx/README.md +++ b/awx/README.md @@ -1,5 +1,7 @@ # AWX — tsys-awx.knel.net +> **Redmine:** [#361](https://projects.knownelement.com/issues/361) (deployment, closed) · [#371](https://projects.knownelement.com/issues/371) (HTTPS/TLS, open) + Ansible AWX deployment on a dedicated k3s single-node VM. **[→ Deployment Plan](DEPLOYMENT.md)** · **[→ Status](../../STATUS.md)** diff --git a/dcinfra/console/README.md b/dcinfra/console/README.md index e34b8cc..a106078 100644 --- a/dcinfra/console/README.md +++ b/dcinfra/console/README.md @@ -1,130 +1,132 @@ -# Console Management (ser2net + conman) - -Network-accessible serial console management for all production network -switches and routers, running on **pfv-tsys4** (storage server). - -## Architecture - -``` -USB-DB9 adapters → udev symlinks (/dev/consoles/) → ser2net telnet(rfc2217) TCP → conman (logging + multiplexing) -``` - -ser2net owns the physical serial devices and exposes them on TCP ports -using the **telnet(rfc2217) protocol** bound to the **Tailscale interface -only** (`100.70.77.93:200X`). conman connects to those TCP ports via -telnet for session logging, output capture, and multi-user console -sharing. - -**Why telnet(rfc2217)?** The serial devices send ` - ` (LF+CR) line +# Console Management (ser2net + conman) + +> **Redmine:** [#360](https://projects.knownelement.com/issues/360) (deployment, closed) · [#373](https://projects.knownelement.com/issues/373) (pfv-r2-sw fix, open) + +Network-accessible serial console management for all production network +switches and routers, running on **pfv-tsys4** (storage server). + +## Architecture + +``` +USB-DB9 adapters → udev symlinks (/dev/consoles/) → ser2net telnet(rfc2217) TCP → conman (logging + multiplexing) +``` + +ser2net owns the physical serial devices and exposes them on TCP ports +using the **telnet(rfc2217) protocol** bound to the **Tailscale interface +only** (`100.70.77.93:200X`). conman connects to those TCP ports via +telnet for session logging, output capture, and multi-user console +sharing. + +**Why telnet(rfc2217)?** The serial devices send ` + ` (LF+CR) line endings instead of standard ` -`. Raw TCP transport caused conman's -telnet NVT to strip bare CR characters, producing stair-stepped output. -With telnet(rfc2217) on both sides, binary mode is negotiated and CR/LF -translation is handled correctly by the telnet layer. - -**conman and ser2net do NOT share ports** — only one process can open a -serial device at a time. ser2net owns the physical device; conman connects -over TCP. - -## The USB Enumeration Problem (SOLVED) - -The 9 Prolific USB-to-DB9 adapters (`067b:2303`) on pfv-tsys4 have **no -unique USB serial numbers** and get assigned `/dev/ttyUSB0-8` based on -enumeration order, which shifts on every boot. This made the old -`/root/conmap` + manual `screen` workflow break after every reboot. - -**Fix:** udev rules pin each adapter by its **ID_PATH** (physical USB port -topology), which is stable across reboots regardless of enumeration order. -Each adapter gets a named symlink in `/dev/consoles/` that never changes. - -The udev rules are generated from `mapping.txt`, which maps each adapter's -ID_PATH to a console name and TCP port. To re-map after physically moving -an adapter, update `mapping.txt` and re-run `setup.sh`. - -**Fallback:** if udev trigger doesn't create symlinks for already-discovered -devices (common on first run), `setup.sh` creates them manually by matching -ID_PATH. On subsequent boots, udev creates them automatically. - -## Port Assignments - -| TCP Port | Console Name | ID_PATH | Description | -|----------|-------------|---------|-------------| -| 2001 | pfv-core-sw01 | usb-0:1.5.4.4 | Dell PowerConnect 5448 (core switch) | -| 2002 | pfv-tor3-mgmt | usb-0:1.6.3.1 | Rack 3 management TOR switch | -| 2003 | pfv-tor3-stor | usb-0:1.6.3.3.2 | Rack 3 storage TOR switch | -| 2004 | pfv-rrinfra-rtr | usb-0:1.6.3.3.1 | Cisco router (rrinfra) | -| 2005 | pfv-r2-tor-top | usb-0:1.6.3.3.3 | Rack 2 top-of-rack switch | -| 2006 | subodev-torsw | usb-0:1.5.4.1 | Suborbital device TOR switch | -| 2007 | pfv-r2-sw | usb-0:1.6.3.2 | Rack 2 old Dell switch | - -All ports listen on the Tailscale IP (`100.70.77.93`) using telnet(rfc2217). - -## Scripts - -| Script | Purpose | -|--------|---------| -| [`mapping.txt`](mapping.txt) | Source of truth: TCP port ↔ ID_PATH ↔ name ↔ baud | -| [`generate-config.sh`](generate-config.sh) | Generates udev rules, ser2net.yaml, conman.conf from mapping.txt | -| [`setup.sh`](setup.sh) | Full deploy: generate configs, create symlinks, restart services | -| [`discover.sh`](discover.sh) | Read-only discovery of USB adapters, existing config, services | - -## Usage - -### Connect to a console - -**Primary method — conman client (with logging + multiplexing):** - -```bash -# From any Tailscale-connected workstation: -conman -d pfv-tsys4:7890 -f pfv-core-sw01 # connect to console -conman -d pfv-tsys4:7890 -q # list all consoles -``` - -Escape sequence: `&.` to disconnect, `&?` for help. - -**Direct telnet (emergency only — conflicts with conman):** - -```bash -# Direct telnet to ser2net works ONLY when conmand is stopped, because -# conmand maintains persistent connections to all 7 TCP ports. Use: -ssh pfv-tsys4 'systemctl stop conmand' -telnet pfv-tsys4 2001 # pfv-core-sw01 -ssh pfv-tsys4 'systemctl start conmand' # restart when done -``` - -**Do NOT use telnet while conmand is running** — conmand will reconnect -and kick your telnet session immediately ("Connection closed by foreign host"). -The correct workflow is conman client → conmand → ser2net → device. - -### Re-deploy after changing mapping.txt - -```bash -PROX_HOST=pfv-tsys4 bash tests/remote.sh prox 'bash /root/console/setup.sh' -``` - -### Find the ID_PATH for a new adapter - -```bash -PROX_HOST=pfv-tsys4 bash tests/remote.sh prox-file console/discover.sh -``` - -Then match the new adapter's ID_PATH to its physical location and add a line -to `mapping.txt`. - -## Files on pfv-tsys4 - -| File | Purpose | -|------|---------| -| `/etc/udev/rules.d/99-console-ports.rules` | Stable symlinks by ID_PATH | -| `/etc/ser2net.yaml` | ser2net config (telnet rfc2217 TCP ports → serial symlinks) | -| `/etc/conman.conf` | conman config (CONSOLE entries between markers) | -| `/etc/systemd/system/conmand.service` | systemd unit for conmand | -| `/root/console/mapping.txt` | Copy of the source-of-truth mapping | -| `/root/console/setup.sh` | Setup script (re-runnable) | -| `/root/console/generate-config.sh` | Config generator | - -## Old workflow (replaced) - -The old `/root/conmap` file and manual `screen` sessions are no longer -needed. The new setup is fully automated and survives reboots. +`. Raw TCP transport caused conman's +telnet NVT to strip bare CR characters, producing stair-stepped output. +With telnet(rfc2217) on both sides, binary mode is negotiated and CR/LF +translation is handled correctly by the telnet layer. + +**conman and ser2net do NOT share ports** — only one process can open a +serial device at a time. ser2net owns the physical device; conman connects +over TCP. + +## The USB Enumeration Problem (SOLVED) + +The 9 Prolific USB-to-DB9 adapters (`067b:2303`) on pfv-tsys4 have **no +unique USB serial numbers** and get assigned `/dev/ttyUSB0-8` based on +enumeration order, which shifts on every boot. This made the old +`/root/conmap` + manual `screen` workflow break after every reboot. + +**Fix:** udev rules pin each adapter by its **ID_PATH** (physical USB port +topology), which is stable across reboots regardless of enumeration order. +Each adapter gets a named symlink in `/dev/consoles/` that never changes. + +The udev rules are generated from `mapping.txt`, which maps each adapter's +ID_PATH to a console name and TCP port. To re-map after physically moving +an adapter, update `mapping.txt` and re-run `setup.sh`. + +**Fallback:** if udev trigger doesn't create symlinks for already-discovered +devices (common on first run), `setup.sh` creates them manually by matching +ID_PATH. On subsequent boots, udev creates them automatically. + +## Port Assignments + +| TCP Port | Console Name | ID_PATH | Description | +|----------|-------------|---------|-------------| +| 2001 | pfv-core-sw01 | usb-0:1.5.4.4 | Dell PowerConnect 5448 (core switch) | +| 2002 | pfv-tor3-mgmt | usb-0:1.6.3.1 | Rack 3 management TOR switch | +| 2003 | pfv-tor3-stor | usb-0:1.6.3.3.2 | Rack 3 storage TOR switch | +| 2004 | pfv-rrinfra-rtr | usb-0:1.6.3.3.1 | Cisco router (rrinfra) | +| 2005 | pfv-r2-tor-top | usb-0:1.6.3.3.3 | Rack 2 top-of-rack switch | +| 2006 | subodev-torsw | usb-0:1.5.4.1 | Suborbital device TOR switch | +| 2007 | pfv-r2-sw | usb-0:1.6.3.2 | Rack 2 old Dell switch | + +All ports listen on the Tailscale IP (`100.70.77.93`) using telnet(rfc2217). + +## Scripts + +| Script | Purpose | +|--------|---------| +| [`mapping.txt`](mapping.txt) | Source of truth: TCP port ↔ ID_PATH ↔ name ↔ baud | +| [`generate-config.sh`](generate-config.sh) | Generates udev rules, ser2net.yaml, conman.conf from mapping.txt | +| [`setup.sh`](setup.sh) | Full deploy: generate configs, create symlinks, restart services | +| [`discover.sh`](discover.sh) | Read-only discovery of USB adapters, existing config, services | + +## Usage + +### Connect to a console + +**Primary method — conman client (with logging + multiplexing):** + +```bash +# From any Tailscale-connected workstation: +conman -d pfv-tsys4:7890 -f pfv-core-sw01 # connect to console +conman -d pfv-tsys4:7890 -q # list all consoles +``` + +Escape sequence: `&.` to disconnect, `&?` for help. + +**Direct telnet (emergency only — conflicts with conman):** + +```bash +# Direct telnet to ser2net works ONLY when conmand is stopped, because +# conmand maintains persistent connections to all 7 TCP ports. Use: +ssh pfv-tsys4 'systemctl stop conmand' +telnet pfv-tsys4 2001 # pfv-core-sw01 +ssh pfv-tsys4 'systemctl start conmand' # restart when done +``` + +**Do NOT use telnet while conmand is running** — conmand will reconnect +and kick your telnet session immediately ("Connection closed by foreign host"). +The correct workflow is conman client → conmand → ser2net → device. + +### Re-deploy after changing mapping.txt + +```bash +PROX_HOST=pfv-tsys4 bash tests/remote.sh prox 'bash /root/console/setup.sh' +``` + +### Find the ID_PATH for a new adapter + +```bash +PROX_HOST=pfv-tsys4 bash tests/remote.sh prox-file console/discover.sh +``` + +Then match the new adapter's ID_PATH to its physical location and add a line +to `mapping.txt`. + +## Files on pfv-tsys4 + +| File | Purpose | +|------|---------| +| `/etc/udev/rules.d/99-console-ports.rules` | Stable symlinks by ID_PATH | +| `/etc/ser2net.yaml` | ser2net config (telnet rfc2217 TCP ports → serial symlinks) | +| `/etc/conman.conf` | conman config (CONSOLE entries between markers) | +| `/etc/systemd/system/conmand.service` | systemd unit for conmand | +| `/root/console/mapping.txt` | Copy of the source-of-truth mapping | +| `/root/console/setup.sh` | Setup script (re-runnable) | +| `/root/console/generate-config.sh` | Config generator | + +## Old workflow (replaced) + +The old `/root/conmap` file and manual `screen` sessions are no longer +needed. The new setup is fully automated and survives reboots. diff --git a/dcinfra/powerman/README.md b/dcinfra/powerman/README.md index adcd136..2607c91 100644 --- a/dcinfra/powerman/README.md +++ b/dcinfra/powerman/README.md @@ -1,5 +1,7 @@ # Powerman PDU Management +> **Redmine:** [#359](https://projects.knownelement.com/issues/359) (deployment, closed) · [#374](https://projects.knownelement.com/issues/374) (outlet renaming, open) + Centralized power management for the Cyclades AlterPath PM10i PDU via [Powerman](https://github.com/chaos/powerman), running on pfv-tsys1. diff --git a/dcinfra/ups/README.md b/dcinfra/ups/README.md index 5ee3b0f..112851d 100644 --- a/dcinfra/ups/README.md +++ b/dcinfra/ups/README.md @@ -1,5 +1,7 @@ # UPS Management (NUT — Network UPS Tools) +> **Redmine:** [#340](https://projects.knownelement.com/issues/340) (APC, closed) · [#372](https://projects.knownelement.com/issues/372) (Tripp Lite, open) + Centralized UPS monitoring for the server room via [NUT](https://networkupstools.org/), running on **pfv-tsys1**. USB HID UPS units feed one `upsd` network server; Home Assistant polls it over Tailscale for diff --git a/k8s/README.md b/k8s/README.md index dc092f5..4c60908 100644 --- a/k8s/README.md +++ b/k8s/README.md @@ -1,5 +1,7 @@ # k8s/ — pfv-k8s Cluster Setup Scripts +> **Redmine:** [#362](https://projects.knownelement.com/issues/362) (initial build, closed) · [#367](https://projects.knownelement.com/issues/367) (rebuild, open) · [#368](https://projects.knownelement.com/issues/368) (worker join, open) + Scripts to bootstrap and manage the k3s control plane on cnode1/2/3. All cluster communication goes over Tailscale IPs — no LAN traffic. diff --git a/netinfra/dns-cluster-setup/README.md b/netinfra/dns-cluster-setup/README.md index 244bf11..52633a9 100644 --- a/netinfra/dns-cluster-setup/README.md +++ b/netinfra/dns-cluster-setup/README.md @@ -1,5 +1,7 @@ # Technitium DNS Cluster Setup +> **Redmine:** [#357](https://projects.knownelement.com/issues/357) (deployment, closed) + Replicates the production Technitium DNS Server from `tailscale-router` to the `pfv-netinfra-01/02` pair and configures them as a primary/secondary cluster with automatic zone transfers.