auto-openconnect

A secure, automated OpenConnect VPN client for Linux with GNOME keyring-based credential management and TOML configuration. Automatically generates OTP tokens and manages VPN connections with enterprise-grade security.

🚀 Features

🔐 Secure Credential Management: Uses GNOME keyring for OAuth tokens and PINs
⚡ Automated OTP Generation: Generates time-based OTP tokens automatically
📋 TOML Configuration: Clean, structured configuration in ~/.config/vpn/config.toml
🛡️ Enterprise Security: Supports F5 BigIP and other enterprise VPN protocols
🔍 Comprehensive Logging: Detailed logs via systemd journal (journalctl -t AUTO-VPN)
� VPN Monitoring: Automatic reconnection on network changes, suspend/resume, and idle detection
�🧪 Fully Tested: Comprehensive test suite covering all functionality
🐍 Modern Python: Requires Python 3.13+ with full type annotations
🐧 Linux Native: Designed specifically for Linux with GNOME desktop

💻 Installation

Prerequisites

Python 3.13+ (required)
Linux with systemd (for logging)
GNOME Desktop Environment (for keyring integration)
OpenConnect (for VPN connectivity)

System Dependencies

Automated Installation (Recommended)

Use the included Makefile for automatic dependency installation:

# Show available commands
make help

# Detect your OS and install dependencies
make install

# Install VPN monitoring system (requires install first)
make install-vpn-monitor

# Test installation in Docker containers
make test

# Test VPN monitor installation
make test-vpn-monitor

# Test specific distribution only
make test fedora
make test-vpn-monitor ubuntu

Manual Installation

Fedora/CentOS/RHEL

# Install system dependencies
sudo dnf install python3.13 python3.13-pip openconnect libsecret-tools gnome-keyring hatch

Ubuntu/Debian

# Install system dependencies
sudo apt update
sudo apt install python3.13 python3.13-pip openconnect libsecret-tools gnome-keyring hatch

Install from PyPI

pip install auto-openconnect

Install for Development

git clone https://github.com/vcwild/auto-openconnect.git
cd auto-openconnect
pip install -e .

🚀 Quick Start

1. Create Configuration

mkdir -p ~/.config/vpn
cat > ~/.config/vpn/config.toml << EOF
[vpn]
user = "your_username"
vpn = "https://your-vpn-server.com"
protocol = "f5"
EOF

2. Setup Secure Credentials

setup-keyring

This will prompt you to securely store your OAuth token and PIN in the system keyring.

3. Connect to VPN

auto-openconnect

Or use the convenient wrapper script:

vpn on   # Connect
vpn off  # Disconnect
vpn check # Check status

⚙️ Configuration

TOML Configuration File

The main configuration is stored in ~/.config/vpn/config.toml:

[vpn]
# VPN Connection Configuration
user = "your_username"
vpn = "https://your-vpn-server.com"
protocol = "f5"

# Note: Sensitive data (OAuth token and PIN) are stored securely in GNOME keyring

Environment Variables

You can override the default config location:

# For bash/zsh
export AUTO_OPENCONNECT_CONFIG="~/.config/vpn/config.toml"

# For fish shell
set -gx AUTO_OPENCONNECT_CONFIG "~/.config/vpn/config.toml"

Keyring Storage

Sensitive credentials are stored securely using GNOME Keyring, which integrates seamlessly with the GNOME desktop environment and provides encrypted storage for secrets.

🔧 Usage

Command Line Interface

# Connect to VPN
auto-openconnect

# Generate password only (for custom scripts)
get-vpn-password

# Setup or update keyring secrets
setup-keyring

# Check connection status
journalctl -t AUTO-VPN -f

🤖 VPN Monitoring

Auto-openconnect includes a comprehensive VPN monitoring system that provides automatic reconnection on various system events, ensuring your VPN connection stays active and reliable.

Features

🔄 Network Change Detection: Automatically reconnects when switching between WiFi networks or ethernet connections
😴 Suspend/Resume Handling: Reconnects VPN after laptop sleep/wake cycles
⏰ Idle Detection: Monitors user activity and reconnects when returning from idle (>5 minutes)
🌐 Connectivity Monitoring: Detects VPN failures and automatically reconnects
🧠 Smart Logic: Only attempts connection when internet connectivity is available
📝 Comprehensive Logging: Tracks all VPN activities and decisions in ~/.local/share/vpn-monitor.log

Installation

Install the VPN monitoring system:

# Install VPN monitoring (requires base installation first)
make install-vpn-monitor

# Or run the installation script directly
./scripts/install-vpn-monitor.sh

This installs:

VPN Monitor Script: ~/.local/bin/vpn-monitor
Systemd Timer: Runs monitoring every 2 minutes automatically
NetworkManager Dispatcher: Responds to network changes immediately
Documentation: Complete setup and troubleshooting guides

Usage

The VPN monitor runs automatically once installed. You can also control it manually:

# Check monitoring status
systemctl --user status vpn-monitor.timer

# View live monitoring logs
tail -f ~/.local/share/vpn-monitor.log

# Run monitor manually (for testing)
~/.local/bin/vpn-monitor

# Stop/start monitoring
systemctl --user stop vpn-monitor.timer
systemctl --user start vpn-monitor.timer

# Disable monitoring
systemctl --user disable vpn-monitor.timer

Testing Network Events

Test the monitoring system by triggering network events:

# Test network reconnection
sudo nmcli networking off && sleep 5 && sudo nmcli networking on

# Check logs to see monitoring response
tail -f ~/.local/share/vpn-monitor.log

Documentation

For detailed installation instructions, troubleshooting, and advanced configuration:

Installation Guide: scripts/INSTALL-VPN-MONITOR.md
Files Reference: scripts/VPN-MONITOR-FILES.md

Testing

Test the VPN monitor installation in Docker containers:

# Test VPN monitor on all distributions
make test-vpn-monitor

# Test on specific distribution
make test-vpn-monitor fedora
make test-vpn-monitor ubuntu

🧪 Development

Setup Development Environment

git clone https://github.com/vcwild/auto-openconnect.git
cd auto-openconnect

# Install system dependencies
make install

# Install project
hatch run pip install -e .

Development Commands

# Run tests
hatch run test

# Run integration tests
hatch run test-integration

# Lint code
hatch run lint

# Format code
hatch run format

# Type checking
hatch run type-check

# All checks (lint + format + type + test)
hatch run all-checks

Testing Installation

Test the installation process in isolated Docker containers:

# Test base installation on all supported distributions
make test

# Test VPN monitor installation on all distributions
make test-vpn-monitor

# Test specific distribution only
make test fedora
make test-vpn-monitor ubuntu

# Run all tests (base + VPN monitor)
make test-all

The Docker testing uses parameterized containers that test both base installation and VPN monitor installation with the same underlying images, ensuring consistency and faster feedback through layer caching.

Project Structure

auto-openconnect/
├── src/auto_openconnect/
│   ├── auth.py               # Authentication logic
│   ├── config.py             # Configuration management
│   ├── connect.py            # Main connection logic
│   ├── exec.py               # Process execution
│   ├── keyring_utils.py      # Keyring management
│   ├── lib.py                # OTP generation
│   ├── log.py                # Logging setup
│   └── password_generator.py # Password-only entry point
├── tests/                    # Comprehensive test suite
├── scripts/                  # Installation and testing scripts
│   ├── install-deps.sh       # System dependency installer
│   ├── install-vpn-monitor.sh # VPN monitor installer
│   ├── test-install.sh       # Docker-based installation tests
│   ├── vpn                   # VPN control script
│   ├── vpn-monitor           # VPN monitoring script
│   ├── INSTALL-VPN-MONITOR.md # VPN monitor installation guide
│   ├── VPN-MONITOR-FILES.md  # VPN monitor files reference
│   ├── systemd/              # Systemd service files
│   │   ├── vpn-monitor.service # Systemd user service
│   │   └── vpn-monitor.timer   # Systemd user timer
│   └── networkmanager/       # NetworkManager integration
│       └── 99-vpn-monitor    # NetworkManager dispatcher script
├── docker/                   # Docker containers for testing
│   ├── Dockerfile.fedora     # Fedora test environment (parameterized)
│   └── Dockerfile.ubuntu     # Ubuntu test environment (parameterized)
├── Makefile                  # Installation and testing interface
├── pyproject.toml            # Project configuration
└── README.md                # This file

🛡️ Security

Credential Storage

OAuth Tokens: Stored in GNOME keyring with service name auto-openconnect
PINs: Encrypted using GNOME keyring
Configuration: Non-sensitive data in TOML format
Logs: Sensitive data is never logged

Verification

Verify your stored credentials:

# Check OAuth token (first 8 chars)
secret-tool lookup service auto-openconnect key oauth_token | head -c 8

# Check PIN (masked)
secret-tool lookup service auto-openconnect key pin | sed 's/./*/g'

Security Best Practices

Never commit credentials to version control
Use GNOME keyring for all sensitive data
Regularly rotate OAuth tokens and PINs
Monitor logs for suspicious activity
Keep dependencies updated for security patches

🔍 Troubleshooting

Common Issues

Configuration Not Found

# Check config file exists
ls -la ~/.config/vpn/config.toml

# Check config format
cat ~/.config/vpn/config.toml

Keyring Issues

# Verify keyring setup
setup-keyring

# Check keyring backend
python -c "import keyring; print(keyring.get_keyring())"

# Manual keyring test
secret-tool lookup service auto-openconnect key oauth_token

Connection Issues

# Check VPN logs
journalctl -t AUTO-VPN -f

# Check OpenConnect process
ps aux | grep openconnect

# Check network connectivity
ping your-vpn-server.com

Debug Mode

Enable verbose logging:

# Watch logs in real-time
journalctl -t AUTO-VPN -f

# Get recent logs
journalctl -t AUTO-VPN -n 50

Support

Check logs: Use journalctl -t AUTO-VPN -n 20 for recent logs
Run tests: Use hatch run test to verify functionality
Verify config: Ensure ~/.config/vpn/config.toml is properly formatted
Check keyring: Use setup-keyring to verify stored credentials

📝 License

auto-openconnect is distributed under the terms of the MIT license.

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
docker		docker
scripts		scripts
src/auto_openconnect		src/auto_openconnect
tests		tests
.gitignore		.gitignore
LICENSE.txt		LICENSE.txt
Makefile		Makefile
README.md		README.md
pyproject.toml		pyproject.toml

License

vcwild/auto-openconnect

Folders and files

Latest commit

History

Repository files navigation