tessl/pypi-borgbackup

Deduplicated, encrypted, authenticated and compressed backups

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

BorgBackup

Name: tessl/pypi-borgbackup
Author: tessl

BorgBackup is a deduplicating backup program that provides efficient and secure data backup through content-defined chunking deduplication, authenticated encryption (AES-256 with HMAC-SHA256), and multiple compression algorithms. It supports both local and remote backups over SSH with mountable backup archives as filesystems for easy restore operations.

Package Information

Package Name: borgbackup
Package Type: pypi
Language: Python (with C/Cython extensions)
Installation: pip install borgbackup

Core Imports

For JSON API programming:

import subprocess
import json

For internal API access (not recommended, unstable):

import borg
from borg.archiver import main
from borg.repository import Repository
from borg.archive import Archive

Basic Usage

Command-Line Interface with JSON Output (Recommended)

import subprocess
import json

# List archives with JSON output
result = subprocess.run(['borg', 'list', '--json', '/path/to/repo'], 
                       capture_output=True, text=True, check=True)
archives = json.loads(result.stdout)

# Get archive info
result = subprocess.run(['borg', 'info', '--json', '/path/to/repo::archive-name'], 
                       capture_output=True, text=True, check=True)
archive_info = json.loads(result.stdout)

# Create archive with JSON stats (--json implies --stats)
result = subprocess.run(['borg', 'create', '--json', 
                        '/path/to/repo::archive-{now}', '/home/user/documents'], 
                       capture_output=True, text=True, check=True)
create_stats = json.loads(result.stdout)

# List archive contents with JSON Lines output
result = subprocess.run(['borg', 'list', '--json-lines', '/path/to/repo::archive-name'], 
                       capture_output=True, text=True, check=True)
files = [json.loads(line) for line in result.stdout.strip().split('\n') if line]

Note: JSON support is selective in BorgBackup. Commands with --json support: create, info, list (repositories), recreate, import-tar. Commands with --json-lines support: diff, list (archive contents).

Repository Initialization

# Initialize encrypted repository
borg init --encryption=repokey /path/to/repo

# Initialize with passphrase encryption
borg init --encryption=keyfile /path/to/repo

Architecture

BorgBackup's architecture consists of several key components:

Repository: Storage backend managing segments, manifest, and metadata
Archives: Individual backup snapshots with deduplication across time
Chunks: Content-defined variable-size data blocks for deduplication
Cache: Local metadata cache for performance optimization
Encryption: AES-256 encryption with HMAC-SHA256 authentication

The tool uses content-defined chunking for cross-file and cross-archive deduplication, making it highly space-efficient for incremental backups.

Capabilities

Repository Operations

Repository initialization, configuration, and maintenance operations including creation, checking, and upgrades.

# Repository initialization
subprocess.run(['borg', 'init', '--encryption=repokey', repository_path])

# Repository info
result = subprocess.run(['borg', 'info', '--json', repository_path], 
                       capture_output=True, text=True, check=True)

# Repository check
subprocess.run(['borg', 'check', repository_path])

Repository Management

Archive Operations

Archive creation, extraction, listing, and deletion operations for managing backup snapshots.

# Create archive
subprocess.run(['borg', 'create', '--json',
               f'{repository_path}::{archive_name}', *source_paths])

# List archives
result = subprocess.run(['borg', 'list', '--json', repository_path],
                       capture_output=True, text=True, check=True)

# Extract archive
subprocess.run(['borg', 'extract', f'{repository_path}::{archive_name}'])

Archive Operations

Pruning and Maintenance

Archive pruning, repository maintenance, and cleanup operations for managing backup retention policies.

# Prune archives by retention policy
subprocess.run(['borg', 'prune', '--keep-daily=7', '--keep-weekly=4', 
               '--keep-monthly=6', repository_path])

# Compact repository
subprocess.run(['borg', 'compact', repository_path])

Pruning and Maintenance

Mount and Access

Mounting archives as filesystems for browsing and selective file restoration.

# Mount archive as filesystem
subprocess.run(['borg', 'mount', f'{repository_path}::{archive_name}', mount_point])

# Unmount
subprocess.run(['borgfs', 'umount', mount_point])

Mount and Access

Utility Operations

Version information, help system, benchmarking, and advanced lock management for BorgBackup operations.

# Get version information
result = subprocess.run(['borg', 'version'], capture_output=True, text=True, check=True)

# Benchmark performance
subprocess.run(['borg', 'benchmark', 'crud', repository_path, '/tmp/benchmark'])

# Run command with repository lock
subprocess.run(['borg', 'with-lock', repository_path, 'custom-command'])

Utility Operations

Types

class RepositoryInfo:
    """Repository information structure"""
    def __init__(self):
        self.cache: dict
        self.security_dir: str
        self.repository: dict  # Contains id, last_modified, location
        self.encryption: dict  # Contains mode, keyfile
        
class ArchiveInfo:
    """Archive information structure"""
    def __init__(self):
        self.name: str
        self.id: str
        self.start: str  # ISO timestamp
        self.end: str    # ISO timestamp
        self.duration: float
        self.stats: dict  # Contains original_size, compressed_size, deduplicated_size
        
class CreateResult:
    """Result of archive creation"""
    def __init__(self):
        self.archive: dict      # Archive metadata
        self.repository: dict   # Repository state
        self.cache: dict       # Cache statistics