CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a VPN Access Server project that extends OpenVPN functionality with custom MAC address validation and session time management. The system integrates with MySQL for data persistence and is designed for deployment on Ubuntu VPN gateways.

Development Commands

This project uses uv as the package manager and main.py as the unified entry point:

Package Management:

Install dependencies: uv install
Add test dependencies: uv add --group test pytest pytest-cov
Activate virtual environment: source .venv/bin/activate

Console Script Commands (Recommended):

Show help: uv run vpn-access-server --help
Show status: uv run vpn-access-server status
Run tests: uv run vpn-access-server test
Health check: uv run vpn-access-server health-check
Initialize database: uv run vpn-access-server init-db
Seed test data: uv run vpn-access-server seed-data

Direct OpenVPN Integration:

Authentication: uv run vpn-access-server auth (called by OpenVPN)
Session management: uv run vpn-access-server session (called by OpenVPN)

Alternative Direct Python Commands:

Main script: uv run python main.py [command]
Direct script access: python access/auth.py or python access/session.py

Alternative Testing:

Run pytest directly: uv run pytest tests/
Run specific test: uv run pytest tests/test_utils.py

Architecture

The system follows a modular layered architecture with these key components:

Core Components

access/: Python scripts that integrate with OpenVPN hooks (client-connect and client-disconnect)
MySQL Database: Stores users, MAC addresses, and session data
OpenVPN Server: Calls Python scripts during connection events

Module Structure

access/auth.py: User authentication and MAC validation logic
access/session.py: Session tracking and time enforcement
access/db.py: MySQL connection and database queries
access/utils.py: Shared utility functions
access/config.py: Configuration management (DB credentials, constants)

Database Schema

users: User accounts with session limits
mac_addresses: Allowed MAC addresses per user
sessions: Connection session tracking with duration

Integration Flow

OpenVPN receives connection attempt
Calls client-connect Python script with environment variables
Script validates user status, MAC address, and session limits via MySQL
Connection allowed/denied based on validation
On disconnect, client-disconnect script updates session duration

Security Notes

Uses parameterized SQL queries to prevent injection
Database credentials should be secured via environment variables or config files
All validation failures are logged for auditing
Scripts run with minimal privileges in /etc/openvpn/access/ on deployment
Always use uv run command whenever you run a python file in a project or source

3.0 KiB Raw Permalink Blame History