chore: publish pxmon v0.2.0

2026-06-16 21:52:10 +04:00
commit 6b703db02b
69 changed files with 25886 additions and 0 deletions
@@ -0,0 +1,103 @@
+# PXmon RepoTunneling
+
+RepoTunneling gives an `ipfabric` node temporary package repository access
+through a disposable gateway VM.
+
+The node does not receive full internet access. PXmon only adds an `ip rule`
+for the gateway VM address and configures the node package manager to use the
+gateway as an HTTP proxy.
+
+## Topology
+
+```text
+ipfabric node
+  -> ip rule to gateway public IP using the node-specific routing table
+  -> gateway VM with squid
+  -> internet repositories
+```
+
+The routing table is not hard-coded. Always pass the correct table for that
+node with `--table`.
+
+## 1. Prepare The Gateway VM
+
+The gateway VM must have normal internet access and must be reachable from the
+ipfabric node after adding the destination-specific route rule.
+
+If the gateway VM is already managed by PXmon:
+
+```bash
+pxmon cluster repo-tunnel gateway-setup repo-vm \
+  --allow 198.51.100.20/32 \
+  --port 3128
+```
+
+If it is not managed by PXmon, print the setup script and run it manually on the
+gateway VM:
+
+```bash
+pxmon cluster repo-tunnel gateway-script \
+  --allow 198.51.100.20/32 \
+  --port 3128
+```
+
+Use one `--allow` per node source IP/CIDR. Do not leave squid open to the
+internet.
+
+## 2. Enable RepoTunneling On The ipfabric Node
+
+```bash
+pxmon cluster repo-tunnel enable edge-node-1 \
+  --gateway 203.0.113.10:3128 \
+  --gateway-ip 203.0.113.10 \
+  --table 1010 \
+  --manager dnf
+```
+
+`--gateway-ip` is optional when the node can resolve the gateway hostname or
+when `--gateway` is already an IP. It is useful before DNS works through the
+proxy path.
+
+PXmon writes managed package-manager config:
+
+- apt: `/etc/apt/apt.conf.d/99-pxmon-repo-tunnel`
+- dnf: managed block in `/etc/dnf/dnf.conf`
+- yum: managed block in `/etc/yum.conf`
+
+## 3. Install Packages
+
+For a one-shot package operation:
+
+```bash
+pxmon cluster repo-tunnel install edge-node-1 \
+  --gateway 203.0.113.10:3128 \
+  --gateway-ip 203.0.113.10 \
+  --table 1010 \
+  --manager dnf \
+  -- dnf install -y curl jq smartmontools
+```
+
+By default `install` removes the proxy config and matching `ip rule` after the
+command. Add `--keep-enabled` if you want to leave it active.
+
+## 4. Inspect Or Disable
+
+```bash
+pxmon cluster repo-tunnel status edge-node-1
+```
+
+```bash
+pxmon cluster repo-tunnel disable edge-node-1 \
+  --gateway 203.0.113.10:3128 \
+  --gateway-ip 203.0.113.10 \
+  --table 1010
+```
+
+## Notes
+
+- `--table` is required because ipfabric route table IDs differ between
+  servers.
+- Use `--no-rule` only if you already created the needed route rule manually
+  and only want PXmon to manage package proxy config.
+- For AlmaLinux 8, `--manager dnf` is the expected mode.
+- The gateway should be disposable and firewall-restricted.