mirror.py

Getting started

  • Installation
    • Requirements
    • Installing from source
    • CLI entry point
    • Provisioning directories and systemd units
    • External tools required by each sync method
    • Optional dependencies
  • Quickstart
    • 1. Provision the runtime directories
    • 2. Create the configuration file
    • 3. Start the worker
    • 4. Start the daemon
    • 5. Check status
    • Next steps

User guide

  • Configuration
    • Mirror.py Configuration Guide
      • 1. Top-level structure
      • 2. Global settings
      • 3. Package definition (common fields)
      • 4. Per-method settings
      • 5. AI Assistant Protocol
  • Config editor
    • Editing and validation
  • CLI reference
    • Global options
      • mirror –version
    • Service commands
      • mirror setup
      • mirror daemon
      • mirror worker
      • mirror crontab
    • Daemon control commands
      • mirror push
      • mirror config reload
      • mirror tui
    • Plug-in commands
      • mirror plugin config create
    • Standalone synchronization
      • mirror standalone
    • Worker-side workflow commands
      • mirror worker-execute ubuntu
      • mirror worker-execute jigdo
  • State files
    • Path layout
      • Config invariant
    • stat.json — persistent package state
      • Per-package status object
      • statusinfo fields
    • status.json — web status
      • Top-level fields
      • Per-package entry fields
    • Log file layout
  • Troubleshooting
    • Where logs live
    • Checking package status
    • Common issues
      • Package stays in ERROR status
      • Package is stuck in SYNC
      • Permission or UID/GID problems
      • Socket path issues
      • Missing external sync tool binary
    • Reloading configuration

Sync methods

  • Sync methods
    • Method comparison
    • How to choose
  • rsync
    • Options
    • Example
    • Full reference
  • ftpsync
    • Options
    • Example
    • Full reference
  • debmirror
    • Repository selection and verification
    • Content, transport, and cleanup options
    • Example
  • apt-mirror2
    • Package options
    • Repository item options
    • Example
  • lftp
    • Options
    • Example
    • Full reference
  • ubuntu
    • Options
    • Example
    • Full reference
  • jigdo
    • Options
    • Example
    • Full reference
  • bandersnatch
    • Options
    • Example
    • Full reference
  • local
    • Options
    • Example
    • Full reference

Architecture and plugins

  • Architecture
    • Runtime modes
    • Master-worker flow
    • Client-facing master RPC
    • Socket protocol
    • Plug-in lifecycle
    • Module map
    • Persistence and paths
    • Built-in sync methods
  • Writing plug-ins
    • Writing plug-ins for mirror.py
      • Three plug-in categories
      • Quickstart: hello-world event plug-in
      • Plug-in contract
      • API reference
      • Config schema
      • Per-plugin config files
      • Bootstrap order (why this matters for sync plug-ins)
      • Naming conventions
      • Trust model
      • Future: pluggy adoption
      • Worked example
  • Example: echo event plug-in
    • mirror-plugin-echo
      • What it demonstrates
      • Install
      • Configure (optional)
      • Run
      • Uninstall

Reference

  • API reference
    • mirror
      • conf
      • packages
      • confPath
      • publishPath
      • status
    • mirror.command
    • mirror.config
      • CONFIG_PATH
      • STAT_DATA_PATH
      • STATUS_PATH
      • SOCKET_PATH
      • load()
      • reload()
      • generate_and_save_web_status()
      • save_stat_data()
    • mirror.event
      • on()
      • once()
      • off()
      • post_event()
      • listener()
      • EventManager
    • mirror.logger
      • PromptHandler
      • DynamicGzipRotatingFileHandler
      • input()
      • compress_file()
      • create_logger()
      • close_logger()
      • setup_logger()
      • get_log_path()
      • get()
      • exists()
      • reattach_logger()
    • mirror.plugin
      • Versioning
      • StatusOutput
      • ConfigCreateResult
      • PluginRecord
      • sync_plugin()
      • event_plugin()
      • status_plugin()
      • load_builtin_plugins()
      • load_external_plugins()
      • get_record()
      • get_config()
    • mirror.socket
      • BaseServer
      • BaseClient
      • HandshakeInfo
      • expose()
      • init()
      • stop()
    • mirror.structure
      • Options
      • PackageSettings
      • Package
      • Packages
      • PluginSettings
      • Config
    • mirror.sync
      • set_standalone_mode()
      • get_standalone_result()
      • get_module()
      • mark_watchdog_fired()
      • release_watchdog_fired()
      • should_kill_for_max_runtime()
      • start()
      • get_extra_args()
      • on_sync_done()
      • execute()
    • mirror.toolbox
      • parse_iso_duration()
      • format_iso_duration()
      • parse_file_mode()
      • set_rsync_user()
      • has_root_or_sudo()
      • command_exists()
    • mirror.worker
      • Job
      • create()
      • get()
      • get_all()
      • prune_finished()
      • manage()
  • Contributing
    • Development setup
    • Building documentation
    • Deploying documentation
    • Keeping sync-method docs in sync
    • Integration testing
      • Integration Tests
mirror.py
  • Search

© Copyright 2026, SPARCS@KAIST.

Built with Sphinx using a theme provided by Read the Docs.