docs: add comprehensive security and authentication documentation
lint / docker (push) Waiting to run
lint / docker (push) Waiting to run
Add new documentation sections covering security best practices and authentication system architecture. Update Sphinx configuration and dependencies to support documentation improvements. Changes include: - New security.rst with SSH key management, network security, secrets management - New authentication.rst documenting pluggable auth system and provider setup - Updated Sphinx config to use Alabaster theme and add sphinx-tabs extension - Added docs extra dependencies in pyproject.toml for documentation builds - Updated example configs to use Ed25519 instead of deprecated DSA keys - Added .python-version file for consistent Python version management - Added CLAUDE.md project instructions for AI-assisted development - Minor Dockerfile cleanup removing commented pip install line 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,156 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
TISBackup is a server-side backup orchestration system written in Python. It executes scheduled backups of various data sources (databases, files, VMs) from remote Linux and Windows systems. The project consists of:
|
||||
|
||||
- A CLI tool ([tisbackup.py](tisbackup.py)) for executing backups, cleanup, and monitoring
|
||||
- A Flask web GUI ([tisbackup_gui.py](tisbackup_gui.py)) for managing backups
|
||||
- A pluggable backup driver architecture in [libtisbackup/](libtisbackup/)
|
||||
- Task queue system using Huey with Redis ([tasks.py](tasks.py), [config.py](config.py))
|
||||
- Docker-based deployment with cron scheduling
|
||||
|
||||
## Development Commands
|
||||
|
||||
### Dependency Management
|
||||
```bash
|
||||
# Install dependencies (uses uv)
|
||||
uv sync --locked
|
||||
|
||||
# Update dependencies
|
||||
uv lock
|
||||
```
|
||||
|
||||
### Linting
|
||||
```bash
|
||||
# Run ruff linter
|
||||
ruff check .
|
||||
|
||||
# Auto-fix linting issues
|
||||
ruff check --fix .
|
||||
```
|
||||
|
||||
### Running the Application
|
||||
|
||||
**Web GUI (development):**
|
||||
```bash
|
||||
python3 tisbackup_gui.py
|
||||
# Runs on port 8080, requires config at /etc/tis/tisbackup_gui.ini
|
||||
```
|
||||
|
||||
**CLI Commands:**
|
||||
```bash
|
||||
# Run backups
|
||||
python3 tisbackup.py -c /etc/tis/tisbackup-config.ini backup
|
||||
|
||||
# Run specific backup section
|
||||
python3 tisbackup.py -c /etc/tis/tisbackup-config.ini -s section_name backup
|
||||
|
||||
# Cleanup old backups
|
||||
python3 tisbackup.py -c /etc/tis/tisbackup-config.ini cleanup
|
||||
|
||||
# Check backup status (for Nagios)
|
||||
python3 tisbackup.py -c /etc/tis/tisbackup-config.ini checknagios
|
||||
|
||||
# List available backup drivers
|
||||
python3 tisbackup.py listdrivers
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
# Build image
|
||||
docker build . -t tisbackup:latest
|
||||
|
||||
# Run via docker compose (see README.md for full setup)
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
**Main Entry Points:**
|
||||
- [tisbackup.py](tisbackup.py) - CLI application with argument parsing and action routing (backup, cleanup, checknagios, etc.)
|
||||
- [tisbackup_gui.py](tisbackup_gui.py) - Flask web application providing UI for backup management and status monitoring
|
||||
- [tasks.py](tasks.py) - Huey task definitions for async operations (export_backup)
|
||||
|
||||
**Backup Driver System:**
|
||||
|
||||
All backup logic is implemented via driver classes in [libtisbackup/](libtisbackup/):
|
||||
|
||||
- Base class: `backup_generic` in [common.py](libtisbackup/common.py:565) (abstract)
|
||||
- Each driver inherits from `backup_generic` and implements specific backup logic
|
||||
- Drivers are registered via the `register_driver()` decorator function
|
||||
- Configuration is read from INI files using the `read_config()` method
|
||||
|
||||
**Available Drivers:**
|
||||
- `backup_rsync` / `backup_rsync_ssh` - File-based backups via rsync
|
||||
- `backup_rsync_btrfs` / `backup_rsync__btrfs_ssh` - Btrfs snapshot-based backups
|
||||
- `backup_mysql` - MySQL database dumps
|
||||
- `backup_pgsql` - PostgreSQL database dumps
|
||||
- `backup_oracle` - Oracle database backups
|
||||
- `backup_sqlserver` - SQL Server backups
|
||||
- `backup_samba4` - Samba4 AD backups
|
||||
- `backup_xva` / `backup_xcp_metadata` - XenServer VM backups
|
||||
- `backup_vmdk` - VMware VMDK backups
|
||||
- `backup_switch` - Network switch configuration backups
|
||||
- `backup_null` - No-op driver for testing
|
||||
|
||||
**State Management:**
|
||||
- SQLite database tracks backup history, status, and statistics
|
||||
- `BackupStat` class in [common.py](libtisbackup/common.py) handles DB operations
|
||||
- Database location: `{backup_base_dir}/log/tisbackup.sqlite`
|
||||
|
||||
### Configuration
|
||||
|
||||
Two separate INI configuration files:
|
||||
|
||||
1. **tisbackup-config.ini** - Backup definitions
|
||||
- `[global]` section with defaults (backup_base_dir, backup_retention_time, maximum_backup_age)
|
||||
- One section per backup job with driver type and parameters
|
||||
|
||||
2. **tisbackup_gui.ini** - GUI settings
|
||||
- Points to tisbackup-config.ini location(s)
|
||||
- Defines admin email, base directories
|
||||
|
||||
### Task Queue
|
||||
|
||||
- Uses Huey (Redis-backed) for async job processing
|
||||
- Currently implements `run_export_backup` for exporting backups to external storage
|
||||
- Task state tracked in tasks.sqlite
|
||||
|
||||
### Docker Deployment
|
||||
|
||||
Two-container architecture:
|
||||
- **tisbackup_gui**: Runs Flask web interface
|
||||
- **tisbackup_cron**: Runs scheduled backups via cron (executes [backup.sh](backup.sh) at 03:59 daily)
|
||||
|
||||
## Code Style
|
||||
|
||||
- Line length: 140 characters (configured in pyproject.toml)
|
||||
- Ruff ignores: F401, F403, F405, E402, E701, E722, E741
|
||||
- Python 3.13+ required
|
||||
|
||||
## Important Patterns
|
||||
|
||||
**Adding a new backup driver:**
|
||||
1. Create `backup_<type>.py` in [libtisbackup/](libtisbackup/)
|
||||
2. Inherit from `backup_generic`
|
||||
3. Set class attributes: `type`, `required_params`, `optional_params`
|
||||
4. Implement abstract methods: `do_backup()`, `cleanup()`, `checknagios()`
|
||||
5. Register with `register_driver(backup_<type>)`
|
||||
6. Import in [tisbackup.py](tisbackup.py)
|
||||
|
||||
**SSH Operations:**
|
||||
- Uses paramiko for SSH connections
|
||||
- Supports both RSA and DSA keys
|
||||
- Private key path specified per backup section via `private_key` parameter
|
||||
- Pre/post-exec hooks run remote commands via SSH
|
||||
|
||||
**Path Handling:**
|
||||
- Module imports use sys.path manipulation to include lib/ and libtisbackup/
|
||||
- All backup drivers expect absolute paths for backup_dir
|
||||
- Backup directory structure: `{backup_base_dir}/{section_name}/{timestamp}/`
|
||||
Reference in New Issue
Block a user