Update documentation for native Docker architecture
Some checks failed
Test / test (push) Has been cancelled
Some checks failed
Test / test (push) Has been cancelled
- Rewrote description.md with current architecture - Removed README.md (outdated Windows VM docs) - Added install/uninstall instructions for host services
This commit is contained in:
@@ -1,258 +0,0 @@
|
||||
# Rego-Tunnel VPN Bridge
|
||||
|
||||
This app runs a Windows VM inside a Docker container with Cisco AnyConnect VPN, providing transparent access to VPN-protected resources (IBM i at 10.35.33.230) from the local network.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Laptop (192.168.0.230) │
|
||||
│ Route: 172.31.0.0/24 via 192.168.0.150 │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Linux Host (192.168.0.150 / 192.168.1.150) │
|
||||
│ │
|
||||
│ rego-routing.service: │
|
||||
│ - Routes 172.32.0.0/24 and 10.35.33.0/24 via 172.31.0.10 │
|
||||
│ - Removes Docker nft isolation rules for 172.31.0.10 │
|
||||
│ - DOCKER-USER iptables rules for forwarding │
|
||||
│ │
|
||||
│ Bridge: br-vpn-rego (172.31.0.1/24) │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Container: rego-tunnel (172.31.0.10) │
|
||||
│ │
|
||||
│ start.sh: │
|
||||
│ - socat: port 2222 → VM:2222 (SSH to VM) │
|
||||
│ - DNAT: ports 22,23,446,448,449,8470-8476,2000-2020,3000-3020, │
|
||||
│ 10000-10020,36000-36010 → VM │
|
||||
│ - MASQUERADE for docker bridge │
|
||||
│ │
|
||||
│ Internal docker bridge: 172.32.0.1/24 │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Windows VM (172.32.0.20) │
|
||||
│ │
|
||||
│ SSH Server: port 2222 │
|
||||
│ Cisco AnyConnect VPN: connected to corporate network │
|
||||
│ VPN IP: 10.215.x.x │
|
||||
│ │
|
||||
│ Portproxy rules (persistent): │
|
||||
│ - 0.0.0.0:22 → 10.35.33.230:22 │
|
||||
│ - 0.0.0.0:23 → 10.35.33.230:23 │
|
||||
│ - 0.0.0.0:446,448,449 → 10.35.33.230:* │
|
||||
│ - 0.0.0.0:8470-8476 → 10.35.33.230:* │
|
||||
│ - 0.0.0.0:2000-2020 → 10.35.33.230:* │
|
||||
│ - 0.0.0.0:3000-3020 → 10.35.33.230:* │
|
||||
│ - 0.0.0.0:10000-10020 → 10.35.33.230:* │
|
||||
│ - 0.0.0.0:36000-36010 → 10.35.33.230:* │
|
||||
│ │
|
||||
│ vpn-login.js: │
|
||||
│ - Auto-login to Cisco AnyConnect via WebView DevTools │
|
||||
│ - TOTP authentication │
|
||||
│ - Watchdog: monitors VPN and reconnects if dropped │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ IBM i (10.35.33.230) │
|
||||
│ Via Cisco VPN tunnel │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Network Configuration
|
||||
|
||||
### IP Addresses
|
||||
|
||||
| Component | IP Address |
|
||||
|-----------|------------|
|
||||
| Container external (br-vpn-rego) | 172.31.0.10 |
|
||||
| Container internal bridge | 172.32.0.1 |
|
||||
| Windows VM | 172.32.0.20 |
|
||||
| IBM i (via VPN) | 10.35.33.230 |
|
||||
|
||||
### Ports
|
||||
|
||||
| Port | Destination | Purpose |
|
||||
|------|-------------|---------|
|
||||
| 2222 | VM SSH (2222) | SSH access to Windows VM |
|
||||
| 22 | IBM i (via portproxy) | SSH to IBM i |
|
||||
| 23 | IBM i (via portproxy) | Telnet to IBM i |
|
||||
| 446,448,449 | IBM i (via portproxy) | IBM i services |
|
||||
| 8470-8476 | IBM i (via portproxy) | IBM i data ports |
|
||||
| 2000-2020 | IBM i (via portproxy) | Additional ports |
|
||||
| 3000-3020 | IBM i (via portproxy) | Additional ports |
|
||||
| 10000-10020 | IBM i (via portproxy) | Additional ports |
|
||||
| 36000-36010 | IBM i (via portproxy) | Additional ports |
|
||||
| 8006 | Container | Web-based Windows viewer |
|
||||
|
||||
## Host Configuration
|
||||
|
||||
### Systemd Service: rego-routing.service
|
||||
|
||||
Location: `/etc/systemd/system/rego-routing.service`
|
||||
|
||||
This service runs after docker.service and:
|
||||
1. Adds routes for 172.32.0.0/24 and 10.35.33.0/24 via 172.31.0.10
|
||||
2. Adds DOCKER-USER iptables rules for forwarding
|
||||
3. Removes Docker's nft isolation rules that block external access to 172.31.0.10
|
||||
|
||||
```bash
|
||||
# Check status
|
||||
sudo systemctl status rego-routing.service
|
||||
|
||||
# Restart if needed
|
||||
sudo systemctl restart rego-routing.service
|
||||
```
|
||||
|
||||
### Client Route (Windows Laptop)
|
||||
|
||||
Add a persistent route to reach the container network:
|
||||
|
||||
```cmd
|
||||
route add 172.31.0.0 mask 255.255.255.0 192.168.0.150 -p
|
||||
```
|
||||
|
||||
Where 192.168.0.150 is the Linux host IP.
|
||||
|
||||
## Files
|
||||
|
||||
### vpn_scripts/start.sh
|
||||
|
||||
Startup script that runs before the Windows VM entry.sh:
|
||||
- Installs required packages (socat, openssh-client, netcat-openbsd)
|
||||
- Sets up SSH key for VM access
|
||||
- Waits for Windows VM to boot
|
||||
- Configures iptables MASQUERADE and FORWARD rules
|
||||
- Sets up socat for SSH forwarding (port 2222)
|
||||
- Configures DNAT rules for all IBM i ports
|
||||
|
||||
**Important**: Uses `return 0` (not `exit 0`) at the end because it's sourced.
|
||||
|
||||
### vpn_scripts/vpn-login.js
|
||||
|
||||
Automated Cisco AnyConnect VPN login:
|
||||
- Connects via WebView DevTools protocol (port 9222)
|
||||
- Handles Microsoft/ADFS authentication
|
||||
- Generates TOTP codes for 2FA
|
||||
- Watchdog mode: monitors VPN every 2 minutes, reconnects if dropped
|
||||
|
||||
### vpn_scripts/id_ed25519-lenovo
|
||||
|
||||
SSH private key for accessing the Windows VM from the container.
|
||||
|
||||
## Windows VM Configuration
|
||||
|
||||
### SSH Server
|
||||
|
||||
Windows OpenSSH is configured to listen on port 2222 (not 22) to allow port 22 for IBM i portproxy.
|
||||
|
||||
Config: `C:\ProgramData\ssh\sshd_config`
|
||||
```
|
||||
Port 2222
|
||||
```
|
||||
|
||||
### Portproxy Rules
|
||||
|
||||
Portproxy rules forward IBM i ports through the VPN. These are persistent (stored in registry).
|
||||
|
||||
```cmd
|
||||
# View all portproxy rules
|
||||
netsh interface portproxy show all
|
||||
|
||||
# Add a rule
|
||||
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=22 connectaddress=10.35.33.230 connectport=22
|
||||
|
||||
# Delete all rules
|
||||
netsh interface portproxy reset
|
||||
```
|
||||
|
||||
Rules are defined in: `/etc/runtipi/user-config/runtipi/rego-tunnel/port-proxy.txt`
|
||||
|
||||
### IP Helper Service
|
||||
|
||||
The IP Helper service (iphlpsvc) must be running for portproxy to work:
|
||||
|
||||
```cmd
|
||||
net start iphlpsvc
|
||||
```
|
||||
|
||||
## User Config
|
||||
|
||||
Location: `/etc/runtipi/user-config/runtipi/rego-tunnel/docker-compose.yml`
|
||||
|
||||
```yaml
|
||||
networks:
|
||||
vpn_static-rego:
|
||||
driver: bridge
|
||||
driver_opts:
|
||||
com.docker.network.bridge.name: "br-vpn-rego"
|
||||
ipam:
|
||||
config:
|
||||
- subnet: 172.31.0.0/24
|
||||
|
||||
services:
|
||||
rego-tunnel:
|
||||
entrypoint: ["/bin/bash", "-c", "source /vpn_scripts/start.sh; exec /run/entry.sh"]
|
||||
sysctls:
|
||||
- net.ipv4.conf.all.rp_filter=0
|
||||
- net.ipv4.conf.default.rp_filter=0
|
||||
cap_add:
|
||||
- NET_ADMIN
|
||||
environment:
|
||||
- VM_NET_IP=172.32.0.20
|
||||
volumes:
|
||||
- /etc/runtipi/repos/runtipi/apps/rego-tunnel/vpn_scripts:/vpn_scripts:ro
|
||||
networks:
|
||||
vpn_static-rego:
|
||||
ipv4_address: 172.31.0.10
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Container won't start / restarts immediately
|
||||
|
||||
Check if start.sh has `exit 0` instead of `return 0` at the end. Since it's sourced, `exit` terminates the parent shell.
|
||||
|
||||
### Can't reach container from laptop
|
||||
|
||||
1. Check route on laptop: `route print | findstr 172.31`
|
||||
2. Check rego-routing.service: `sudo systemctl status rego-routing.service`
|
||||
3. Check if Docker nft rules are blocking: `sudo nft list ruleset | grep 172.31`
|
||||
|
||||
### Portproxy not working
|
||||
|
||||
1. Restart IP Helper: `net stop iphlpsvc && net start iphlpsvc`
|
||||
2. Check if SSH is on port 2222: `netstat -an | findstr :22`
|
||||
3. Verify portproxy rules: `netsh interface portproxy show all`
|
||||
|
||||
### VPN not connecting
|
||||
|
||||
1. Check vpn-login.js logs in Windows VM
|
||||
2. Verify time sync (TOTP requires accurate time)
|
||||
3. Check if VPN credentials in vpn-login.js are correct
|
||||
|
||||
### Bridge name too long error
|
||||
|
||||
Linux bridge names are limited to 15 characters. "br-vpn-static-rego" (18 chars) won't work; use "br-vpn-rego" (11 chars).
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Updating vpn_scripts
|
||||
|
||||
1. Edit files in `/etc/runtipi/repos/runtipi/apps/rego-tunnel/vpn_scripts/`
|
||||
2. Commit and push to git
|
||||
3. Run `sudo ./runtipi-cli appstore update`
|
||||
4. Restart app: `sudo ./runtipi-cli app stop rego-tunnel:runtipi && sudo ./runtipi-cli app start rego-tunnel:runtipi`
|
||||
|
||||
### Updating portproxy rules
|
||||
|
||||
1. Edit `/etc/runtipi/user-config/runtipi/rego-tunnel/port-proxy.txt`
|
||||
2. SSH to VM: `ssh -p 2222 docker@172.31.0.10`
|
||||
3. Reset and re-apply: `netsh interface portproxy reset` then run the commands from port-proxy.txt
|
||||
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user