State files
mirror.py separates read-only configuration from mutable runtime state. The
configuration file is never modified after mirror setup; all runtime state is
written to separate files under /var/lib/mirror/ and /var/www/mirror/.
Path layout
Path |
Purpose |
Writable by daemon? |
|---|---|---|
|
Main configuration |
No — read-only at runtime |
|
Persistent package state |
Yes (atomic rewrite on each status change) |
|
Unix sockets ( |
Yes |
|
Daemon logs; per-package logs under |
Yes |
|
Web-accessible status JSON for the mirror UI |
Yes |
Config invariant
/etc/mirror/config.json is read-only during daemon and worker runtime. Only
mirror setup ever writes it. Runtime state — sync status, error counts, log
paths, timestamps — lives exclusively in stat.json. There is intentionally no
Config.save() method; never write to config.json from the daemon.
stat.json — persistent package state
/var/lib/mirror/stat.json is rewritten atomically every time a package
changes status, with file mode 0600. Its default structure contains only
runtime state; package settings, including credentials, are not copied into it:
{
"mirrorname": "<name>",
"packages": {
"<packageid>": {
"lastsync": 0.0,
"timestamp": 0.0,
"status": {
"status": "<STATUS>",
"statusinfo": { ... }
}
}
}
}
lastsync is the last sync timestamp in seconds; timestamp is the last
status transition timestamp in milliseconds. Fields absent in an older file
use their existing defaults when loaded.
On startup or config reload, older state files are rewritten into this format.
Known runtime fields are preserved, including legacy statusinfo.lastsync.
Configuration always comes from config.json.
Status plug-ins can extend or transform this payload. They are trusted code and must avoid including credentials in their contributions or other outputs.
Upgrading existing installations
Update the master, worker, and CLI/TUI together. The package status RPC format uses IPC protocol version 3; version 2 clients and servers reject the mismatch during the handshake. Start the updated worker before the updated master.
mirror setup creates config.json with mode 0600 and restricts an existing
regular config file to 0600 without changing its contents or owner. It rejects
symlinks and other non-regular config paths. For an existing installation,
either rerun setup or restrict the actual config file explicitly:
sudo chmod 0600 /etc/mirror/config.json
Use the actual path when running with a custom --config. Runtime loading
does not change config contents or permissions. The updated daemon writes
stat.json with 0600 on startup and every subsequent save. Verify the
permissions after startup:
sudo stat -c '%a %n' /etc/mirror/config.json /var/lib/mirror/stat.json
Both files should report 600. Existing backups are not rewritten by this
migration. Web status.json and separate plug-in outputs remain 0644.
Per-package status object
Field |
Type |
Description |
|---|---|---|
|
string |
Current package status: |
statusinfo fields
These fields are defined in Package.StatusInfo in mirror/structure/__init__.py.
Field |
Type |
Description |
|---|---|---|
|
string or null |
Path of the most recent error log file. |
|
string or null |
Path of the most recent successful sync log file. |
|
string or null |
Path of the log file for the currently running sync. |
|
integer |
Number of consecutive errors since the last successful sync. Reset to 0 on |
|
float |
Unix timestamp (seconds) of the last successful sync completion. |
|
float |
Unix timestamp (seconds) of the last error. |
status.json — web status
/var/www/mirror/status.json is regenerated when package status changes,
including sync start and completion. It is intended to be served by a web
server so that users and monitoring tools can inspect mirror freshness.
Its shape is:
{
"lastupdate": <timestamp_ms>,
"mirrorname": "<name>",
"lists": ["<packageid>", ...],
"<packageid>": { ... },
...
}
Top-level fields
Field |
Type |
Description |
|---|---|---|
|
float |
Millisecond timestamp of when the status file was last written. |
|
string |
The |
|
array of strings |
Ordered list of package IDs included in this status file. |
Per-package entry fields
Each key in lists has a corresponding top-level entry with the following
fields:
Field |
Type |
Description |
|---|---|---|
|
string |
Human-readable package name. |
|
string |
Package identifier matching the key in |
|
string |
Current status: |
|
string or null |
Sync method in use (e.g. |
|
string |
Sync interval as an ISO 8601 duration or a special token ( |
|
string |
Upstream source URL. |
|
string |
Web-accessible path for this mirror on the local server. |
|
float |
Unix timestamp in seconds of the last completed sync. |
|
array of objects |
Related links, each with |
|
float |
Unix timestamps in seconds from |
|
string or null |
Log paths from |
|
integer |
Consecutive failures since the last success. |
Status plugins can add a plugins object to per-package entries or replace the
default payload through a transform hook.
Log file layout
Daemon log paths come from settings.logger.fileformat; per-package paths
come from settings.logger.packagefileformat. Each has base, folder, and
filename templates. The configuration created by mirror setup uses:
/var/log/mirror/
<year>/<month>/<year>-<month>-<day>.log # daemon log
packages/<year>/<month>/<day>/ # per-package sync logs
<pkgid>.<HH>:<MM>:<SS>.<us>.log
The quickstart example overrides the per-package filename template, placing
the package ID last. Use the configured templates or the paths recorded in
package status to locate logs. settings.logfolder is the base for ftpsync
tool logs; it does not select the daemon or per-package log paths.
Log files are gzip-compressed on rotation when gzip: true is set in the
settings.logger.fileformat and settings.logger.packagefileformat config sections.