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.