Update documentation for native Docker architecture

- Rewrote description.md with current architecture - Removed README.md (outdated Windows VM docs) - Added install/uninstall instructions for host services
2026-01-17 04:01:14 +00:00
parent c3581c7ecc
commit 96d4e32672
2 changed files with 118 additions and 303 deletions
--- a/apps/rego-tunnel/metadata/description.md
+++ b/apps/rego-tunnel/metadata/description.md
@@ -1,71 +1,144 @@
 # Rego Tunnel - Cisco Secure Client VPN

-Run Cisco Secure Client (AnyConnect) with full GUI support in Docker using noVNC.
+Native Docker container running Cisco Secure Client (AnyConnect) with full GUI support via noVNC. Provides transparent VPN access to protected resources from your LAN.

 ## Features

- **Full Cisco Secure Client 5.1.14.145** with GUI
- VPN, DART, and Posture modules pre-installed
- **Web-based VNC access** via noVNC
- Systemd support for proper service management
- **No QEMU or VM overhead** - runs natively in Docker
- **Auto-login with TOTP support** - fully automated connection
- Auto-reconnect on disconnect
+- **Cisco Secure Client 5.1.14.145** - Full GUI with VPN, DART, and Posture modules
+- **Web-based access** via noVNC (port 6080)
+- **Auto-login with TOTP** - Fully automated VPN connection
+- **LAN routing** - Other machines on your network can reach VPN targets
+- **Native Docker** - No QEMU/VM overhead

-## Quick Start
+## Architecture

-1. **Install the app** through Runtipi
-2. **Configure credentials** (optional) through app settings for auto-connect
-3. **Access the VPN GUI** at `http://<your-server>:6080/vnc.html`
-4. Default VNC password: `cisco123`
+```
+LAN Devices ──► Linux Host ──► Container (172.31.0.10) ──► VPN Tunnel ──► Target (10.35.33.230)
+                   │                    │
+                   │                    └── Cisco Secure Client
+                   │                    └── noVNC web UI (port 6080)
+                   │
+                   └── Host routing service
+                       (routes VPN traffic through container)
+```

-## Auto-Connect
+## Installation

-For fully automated VPN connection:
+### 1. Install the app through Runtipi

-1. Fill in your VPN Email, Password, and TOTP Secret in app settings
-2. Enable "Auto-Connect on Start"
-3. The container will automatically connect to VPN on startup
+Configure your VPN credentials in app settings:
+- VPN Email
+- VPN Password
+- TOTP Secret (base32)
+- VPN Host (default: vpn-ord1.dovercorp.com)
+- Target IP (default: 10.35.33.230)

-## Manual Connect
+### 2. Install host routing service (required for LAN access)

-If you prefer manual login:
-
-1. Access the noVNC interface at port 6080
-2. Use the Cisco Secure Client GUI to connect
-3. Enter your credentials manually
-
-## VPN CLI (inside container)
+**Run this ONCE on the host after app install:**

 ```bash
-# Connect to VPN
-docker exec -it rego-tunnel /opt/cisco/secureclient/bin/vpn connect <server>
+/etc/runtipi/repos/runtipi/apps/rego-tunnel/shared/install-host-services.sh
+```

-# Check status
-docker exec -it rego-tunnel /opt/cisco/secureclient/bin/vpn state
+This creates systemd services that route VPN traffic through the container.

-# Disconnect
-docker exec -it rego-tunnel /opt/cisco/secureclient/bin/vpn disconnect
+### 3. Access the VPN GUI
+
+Open `http://<your-server>:6080/vnc.html`
+
+The VPN will auto-connect using your configured credentials.
+
+## Usage
+
+### Access noVNC
+
+Navigate to port 6080 on your server. The cisco-vpn script runs automatically and provides a menu:
+
+```
+1 - Start Cisco AnyConnect
+2 - Copy credentials to clipboard
+3 - Show live TOTP
+4 - Setup IP forwarding rules
+5 - Test connection to target
+6 - Show network status
+7 - Kill all Cisco processes
+8 - Show routing table
+9 - Show /etc/hosts
+q - Quit
+```
+
+### Command line options
+
+```bash
+# Inside container
+cisco-vpn -m          # Menu only (skip auto-connect)
+cisco-vpn -c          # Connect and exit
+cisco-vpn -d          # Disconnect and exit
+cisco-vpn -s          # Show status
+cisco-vpn --help      # Show all options
+```
+
+### View logs
+
+```bash
+# Inside container
+cat /var/log/cisco-vpn/$(date +%Y-%m-%d).log
+
+# On host
+cat /var/log/rego-routing.log
+```
+
+## LAN Access
+
+After the host routing service is installed, any device on your LAN can reach the VPN target:
+
+1. **From the host:** Works automatically
+2. **From other LAN devices:** Add a static route pointing to your host
+
+Example (Windows client):
+```cmd
+route add 10.35.33.230 mask 255.255.255.255 192.168.0.150 -p
+```
+
+Where `192.168.0.150` is your Linux host IP.
+
+## Uninstall
+
+Before removing the app from Runtipi:
+
+```bash
+/etc/runtipi/repos/runtipi/apps/rego-tunnel/shared/uninstall-host-services.sh
 ```

 ## Troubleshooting

-### VPN connects but immediately disconnects
-Check if the DNS files are writable. Restart the container if needed.
-
-### "Unable to start VA" error
-This usually means the DNS files are read-only. Restart the container.
-
 ### noVNC not accessible
-Check if the VNC service is running:
 ```bash
-docker exec rego-tunnel systemctl status vnc.service
+docker exec rego-tunnel_runtipi-rego-tunnel-1 systemctl status vnc.service
+```
+
+### VPN connects but can't reach target
+```bash
+# Check routes inside container
+docker exec rego-tunnel_runtipi-rego-tunnel-1 ip route
+
+# Check host routing
+ip route | grep 10.35.33.230
+```
+
+### Host routing not working
+```bash
+# Check watcher service
+systemctl status rego-routing-watcher.path
+
+# Manually trigger routing
+touch /etc/runtipi/app-data/runtipi/rego-tunnel/restart-routing
 ```

 ## Technical Details

-The container uses:
- `--privileged` mode for systemd and DNS mount manipulation
- `NET_ADMIN` capability for VPN tunnel creation
- `/dev/net/tun` device for the VPN tunnel
- Ports: 6080 (noVNC web UI), 5901 (VNC)
+- **Container IP:** 172.31.0.10 (on br-rego-vpn bridge)
+- **Ports:** 6080 (noVNC), 5901 (VNC)
+- **Privileges:** `--privileged`, `NET_ADMIN`, `/dev/net/tun`
+- **Log retention:** 7 days (auto-cleanup)