NAME

mirrord — mirrortools background daemon service

SYNOPSIS

DESCRIPTION

mirrord is the background daemon for mirror(1). It manages a persistent queue of mirror requests, executes them with configurable worker concurrency, quarantines problematic or failing jobs, and provides both a local Unix domain socket for CLI management and an HTTP server for the Web dashboard and REST API.

Mirror jobs and execution logs are stored in a SQLite database, ensuring jobs survive service restarts. Requests submitted through mirror queue submit are dispatched to worker slots and logged in real time.

The flags are:

-config path

Configuration file to read. The default is ~/.config/mirrortools/config.toml or $MIRROR_CONFIG.

-socket path

Path to the Unix domain socket for local control. The default is $XDG_RUNTIME_DIR/mirrortools/mirrord.sock or ~/.local/state/mirrortools/mirrord.sock.

-http addr

TCP address and port for the Web UI and HTTP API, such as 127.0.0.1:8080. When omitted or empty, only the local Unix domain socket is used.

-password pass

Password protecting the Web UI and HTTP API.

-password-file path

Path to a file containing the password protecting the Web UI and HTTP API.

-concurrency n

Maximum number of worker goroutines running mirror jobs simultaneously. The default is 2.

-db path

Path to the SQLite database file. The default is ~/.local/state/mirrortools/mirrord.db.

-version

Print the version and exit.

QUEUE MANAGEMENT

Jobs in the queue move through several states:

A job that encounters repeated errors (by default 3) or non-transient authentication/permission errors (such as HTTP 403 Forbidden or expired credentials) is automatically quarantined so it does not waste worker slots or risk remote IP bans. Quarantined jobs can be reviewed and retried using mirror queue unquarantine.

SCHEDULING & FAIR DISPATCH

Jobs submitted to mirrord are automatically indexed by their destination site or root domain and hierarchical subpath. When multiple workers are active, the scheduler applies fair-share per-host scheduling: active workers prioritize idle sites so that requests from different domains execute in parallel without starving any single host. Within each site, queued URLs are processed hierarchically in tree order (from top-level directories downward).

Entire sites or subdirectories can be paused, resumed, quarantined, unquarantined, or cancelled in a single operation via the Web UI or mirror(1) CLI using URL or domain prefixes.

WEB UI

When started with -http addr, mirrord serves an embedded, self-contained single-page dashboard. The Web UI provides real-time job monitoring with both hierarchical Site & Subtree and Flat List views, site/subtree batch controls, individual job pause/resume, live log streaming via Server-Sent Events (SSE), manual submission, and in-browser configuration editing.

AUTHENTICATION

When an HTTP listener is configured, authentication can be enabled to protect the Web dashboard and REST API. Local CLI operations over the Unix domain socket remain unauthenticated, protected by local filesystem permissions.

Two authentication mechanisms are supported:

Password authentication

Configured with -password, -password-file, or in [daemon.auth] with password or password-file. In the browser, logging in sets a secure, HTTP-only session cookie. For API requests, the password may be sent via Authorization: Bearer <password> or HTTP Basic authentication.

OAuth 2.0 / OpenID Connect

Configured under [daemon.auth.oauth] with provider settings provider, issuer or endpoints (auth-url, token-url, userinfo-url), client-id, and client-secret or client-secret-file. Optional user authorization can be restricted using allowed-users.

FILES

~/.config/mirrortools/config.toml

The configuration file. Daemon settings go in the [daemon] section.

~/.local/state/mirrortools/mirrord.db

The SQLite database storing jobs, history, and log messages.

$XDG_RUNTIME_DIR/mirrortools/mirrord.sock

The local control socket.

SEE ALSO

mirror(1), mirrorq(1)