GEMINI.md

Project Overview

This project is a VPN Access Server, written in Python, designed to extend an OpenVPN server with custom authentication and session management features. It uses a MySQL database to store user information, authorized MAC addresses, and session data.

The core functionality is to:

Validate MAC Addresses: Ensure only devices with authorized MAC addresses can connect to the VPN.
Enforce Session Time: Manage and enforce session duration policies on a per-user basis.

The architecture is based on OpenVPN's client-connect and client-disconnect hooks, which execute Python scripts to perform the validation logic.

Technologies:

Language: Python 3
Database: MySQL
VPN: OpenVPN (as the execution environment)
Dependencies: mysql-connector-python, pytest

Building and Running

The project is managed via a central command-line interface in main.py.

Initial Setup

Install Dependencies:
```
uv pip install -r requirements.txt
```
(Note: Based on pyproject.toml, you might use uv pip install . or uv pip install -e . for editable mode)
Configure Environment: Create a .env file based on .env.example and provide the necessary database credentials:
```
cp .env.example .env
# Edit .env with your DB settings
```
Initialize the Database: This script will create the necessary tables (employees, mac_addresses, sessions) in the database.
```
python main.py init-db
```

Running the Application

The main application logic is triggered by OpenVPN. However, you can run the individual components for testing or health checks.

Run a Health Check: Verifies the configuration and database connection.
```
python main.py health-check
```
Show Status: Displays the current configuration.
```
python main.py status
```
Run Authentication/Session Logic (Manual Simulation): These commands are intended to be called by OpenVPN but can be run manually if the required environment variables are set.
```
# Simulate OpenVPN client-connect
python main.py auth

# Simulate OpenVPN client-disconnect
python main.py session
```

Running Tests

The project uses pytest for testing.

python main.py test

pytest

Development Conventions

Modular Architecture: The code is structured into modules with clear responsibilities:
- access/auth.py: User authentication and MAC validation.
- access/session.py: Session management.
- access/db.py: Database interaction.
- access/config.py: Configuration loading.
- access/utils.py: Shared utility functions.
Configuration: Configuration is loaded from environment variables, following the 12-factor app methodology. A .env file is used for local development.
Database Management: Database connections are managed through a connection pool in db.py for efficiency. All SQL queries are centralized in this file.
CLI: A single entry point (main.py) provides a consistent way to interact with and manage the application.
Testing: Unit tests are located in the tests/ directory and can be run with pytest.

3.3 KiB Raw Permalink Blame History