Hello! Thanks for visiting! mirrorctl is still a young project, and the documentation is still a work-in-progress.
Configuration

Configuration

The mirrorctl configuration file uses TOML format and defines how repositories are mirrored, including network settings, TLS configuration, snapshot management, and per-mirror options.

Configuration File Location

By default, mirrorctl reads its configuration from /etc/mirrorctl/mirror.toml. You can specify an alternative location using the --config flag with any command.

Complete Example Configuration

Below is a complete example configuration for mirroring Debian Trixie:

# mirrorctl Configuration File
dir = "/var/www/apt/"
max_conns = 10

[log]
level = "info"
format = "text"

[tls]
min_version = "1.2"
max_version = "1.3"
insecure_skip_verify = false
cipher_suites = [
    "TLS_AES_256_GCM_SHA384",
    "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
]
# ca_cert_file = "/path/to/custom-ca.pem"
# client_cert_file = "/path/to/client-cert.pem"
# client_key_file = "/path/to/client-key.pem"
# server_name = "custom-mirror.example.com"

[snapshot]
path = "/var/lib/mirrorctl/snapshots"
default_name_format = "2006-01-02T15-04-05Z"

[snapshot.prune]
keep_last = 5
keep_within = "30d"

[mirrors.debian-trixie]
url = "https://deb.debian.org/debian/"
suites = ["trixie", "trixie-updates"]
sections = ["main", "contrib", "non-free", "non-free-firmware"]
architectures = ["amd64", "arm64"]
mirror_source = true
pgp_key_path = "/etc/mirrorctl/keys/debian-archive-keyring.gpg"
no_pgp_check = false
publish_to_staging = true

[mirrors.debian-trixie.filters]
keep_versions = 3
exclude_patterns = [
    ".*-dbg$",       # Debug packages
    ".*-dev$"        # Development packages
]

[mirrors.debian-trixie.snapshot]
default_name_format = "trixie-2006-01-02"

[mirrors.debian-trixie.snapshot.prune]
keep_last = 10
keep_within = "60d"
# mirrorctl Configuration File

# Global Settings
# ===============

# Base directory where mirrored repositories will be stored
# REQUIRED: Must be an absolute path
dir = "/var/www/apt/"

# Maximum number of concurrent connections per mirror
# Optional: Default is 10
max_conns = 10

# Logging Configuration
# ====================
[log]
# Log level: debug, info, warn, error
# Optional: Default is "info"
level = "info"

# Log format: text, plain, json
# Optional: Default is "text"
format = "text"

# TLS/SSL Configuration
# ====================
[tls]
# Minimum TLS version: "1.2" or "1.3"
# Optional: Default is "1.2"
min_version = "1.2"

# Maximum TLS version: "1.2" or "1.3"
# Optional: Unset allows any supported version
max_version = "1.3"

# Skip certificate verification (INSECURE - testing only!)
# Optional: Default is false
insecure_skip_verify = false

# Path to custom CA certificate file for verification
# Optional: Uses system CA bundle if not specified
# ca_cert_file = "/path/to/custom-ca.pem"

# Client certificate file for mutual TLS authentication
# Optional: Must be paired with client_key_file
# client_cert_file = "/path/to/client-cert.pem"

# Client private key file for mutual TLS authentication
# Optional: Must be paired with client_cert_file
# client_key_file = "/path/to/client-key.pem"

# Allowed cipher suites (empty = Go defaults)
# Optional: Available options:
#   - TLS_AES_128_GCM_SHA256
#   - TLS_AES_256_GCM_SHA384
#   - TLS_CHACHA20_POLY1305_SHA256
#   - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
#   - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
#   - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
#   - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
cipher_suites = [
    "TLS_AES_256_GCM_SHA384",
    "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
]

# Server name for SNI (Server Name Indication)
# Optional: Overrides hostname from URL
# server_name = "custom-mirror.example.com"

# Snapshot Configuration
# =====================
[snapshot]
# Base path where snapshots will be stored
# Optional: Default is "/var/lib/mirrorctl/snapshots"
path = "/var/lib/mirrorctl/snapshots"

# Default snapshot name format (Go time format)
# Optional: Default is "2006-01-02T15-04-05Z"
# Examples:
#   "2006-01-02T15-04-05Z"     -> 2024-01-15T10-30-00Z
#   "2006-01-02"               -> 2024-01-15
#   "20060102-150405"          -> 20240115-103000
default_name_format = "2006-01-02T15-04-05Z"

# Snapshot pruning/retention policy
[snapshot.prune]
# Number of recent snapshots to keep
# Optional: Default is 5
keep_last = 5

# Keep snapshots within duration
# Optional: Format examples: "7d", "2w", "30d"
# Supported units: d (days), w (weeks)
keep_within = "30d"

# Mirror Configurations
# ====================

# Debian Trixie Mirror
[mirrors.debian-trixie]
# Repository URL (http or https)
# REQUIRED
url = "https://deb.debian.org/debian/"

# Distribution suites to mirror
# REQUIRED: For flat repositories, append "/" to suite name
suites = ["trixie", "trixie-updates"]

# Repository sections to mirror
# REQUIRED for non-flat repositories
sections = ["main", "contrib", "non-free", "non-free-firmware"]

# Architectures to mirror
# REQUIRED for non-flat repositories
# Note: "all" architecture is automatically included
architectures = ["amd64", "arm64"]

# Include source packages
# Optional: Default is false
mirror_source = true

# PGP key file path for signature verification
# Optional: Uses system keyring if not specified
# pgp_key_path = "/usr/share/keyrings/debian-archive-keyring.gpg"

# Disable PGP signature verification
# Optional: Default is false (verification enabled)
no_pgp_check = false

# Automatically publish new syncs to staging
# Optional: Default is false
publish_to_staging = true

# Package filtering configuration
[mirrors.debian-trixie.filters]
# Number of package versions to keep (newest first)
# Optional: 0 = keep all versions
keep_versions = 3

# Patterns for excluding packages (regex)
# Optional: Empty = no exclusions
exclude_patterns = [
    ".*-dbg$",       # Debug packages
    ".*-dev$"        # Development packages
]

# Per-mirror snapshot configuration overrides
[mirrors.debian-trixie.snapshot]
# Override global snapshot name format for this mirror
# Optional: Uses global default if not specified
default_name_format = "trixie-2006-01-02"

# Override global pruning policy for this mirror
[mirrors.debian-trixie.snapshot.prune]
keep_last = 10
keep_within = "60d"

Minimal Configuration Example

There’s a lot configured in the example above, but not each item is required. If you want a less complicated example, here is a minimal configuration for Debian Trixie:

dir = "/var/www/apt/"

[mirrors.debian-trixie]
url = "https://deb.debian.org/debian/"
suites = ["trixie", "trixie-updates"]
sections = ["main", "contrib", "non-free", "non-free-firmware"]
architectures = ["amd64", "arm64"]
mirror_source = true
no_pgp_check = true

See Also