94 lines
3.3 KiB
Markdown
94 lines
3.3 KiB
Markdown
|
# 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:
|
||
|
|
1. **Validate MAC Addresses**: Ensure only devices with authorized MAC addresses can connect to the VPN.
|
||
|
|
2. **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
|
||
|
|
|
||
|
|
1. **Install Dependencies:**
|
||
|
|
```bash
|
||
|
|
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)*
|
||
|
|
|
||
|
|
2. **Configure Environment:**
|
||
|
|
Create a `.env` file based on `.env.example` and provide the necessary database credentials:
|
||
|
|
```bash
|
||
|
|
cp .env.example .env
|
||
|
|
# Edit .env with your DB settings
|
||
|
|
```
|
||
|
|
|
||
|
|
3. **Initialize the Database:**
|
||
|
|
This script will create the necessary tables (`employees`, `mac_addresses`, `sessions`) in the database.
|
||
|
|
```bash
|
||
|
|
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.
|
||
|
|
```bash
|
||
|
|
python main.py health-check
|
||
|
|
```
|
||
|
|
|
||
|
|
* **Show Status:**
|
||
|
|
Displays the current configuration.
|
||
|
|
```bash
|
||
|
|
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.
|
||
|
|
```bash
|
||
|
|
# Simulate OpenVPN client-connect
|
||
|
|
python main.py auth
|
||
|
|
|
||
|
|
# Simulate OpenVPN client-disconnect
|
||
|
|
python main.py session
|
||
|
|
```
|
||
|
|
|
||
|
|
### Running Tests
|
||
|
|
|
||
|
|
The project uses `pytest` for testing.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
python main.py test
|
||
|
|
```
|
||
|
|
or
|
||
|
|
```bash
|
||
|
|
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`.
|