lts-backup-cli 2.0.0__py3-none-any.whl

lts_backup_cli/config.py

@@ -0,0 +1,308 @@
+"""Configuration model, persistence and lint. Secrets live in separate 0600 files, never in TOML."""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+import tomli_w
+
+from . import validation as v
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+
+class ConfigError(RuntimeError):
+    pass
+
+
+def config_dir() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "ltsbu"
+
+
+def cache_dir() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(base) / "ltsbu"
+
+
+def default_config_path() -> Path:
+    return config_dir() / "config.toml"
+
+
+VERSION = 2
+
+
+@dataclass
+class KeepPolicy:
+    hourly: int | None = 12
+    daily: int | None = 7
+    weekly: int | None = 4
+    monthly: int | None = 6
+
+
+@dataclass
+class Schedule:
+    every_hours: int = 2
+    minute: int = 0  # offset inside the hour; staggered per repo by schedule.default_schedule
+    weekly_day: str = "Sun"
+    weekly_time: str = "03:00"
+
+
+@dataclass
+class RepoConfig:
+    name: str
+    kind: str  # vhost | db | folder
+    password_file: (
+        str  # local 0600 copy; the server holds its own copy (ServerConfig.password_path)
+    )
+    paths: list[str] = field(default_factory=list)  # on the server (vhost/folder)
+    databases: list[str] = field(default_factory=list)  # db
+    vhost: str | None = None
+    exclude_git: bool = True
+    schedule: Schedule = field(default_factory=Schedule)
+    keep: KeepPolicy = field(default_factory=KeepPolicy)
+
+    def validate(self) -> None:
+        v.label(self.name)
+        v.repo_kind(self.kind)
+        v.abs_path(self.password_file)
+        for p in self.paths:
+            v.remote_abs_path(p)
+        for db in self.databases:
+            v.db_name(db)
+        if self.vhost:
+            v.hostname(self.vhost)
+        v.every_hours(self.schedule.every_hours)
+        if not 0 <= self.schedule.minute <= 59:
+            raise v.ValidationError(f"schedule minute must be 0-59, got {self.schedule.minute}")
+        v.weekday(self.schedule.weekly_day)
+        v.hhmm(self.schedule.weekly_time)
+        for k in (self.keep.hourly, self.keep.daily, self.keep.weekly, self.keep.monthly):
+            v.keep(k)
+
+    def kind_problems(self) -> list[str]:
+        if self.kind == "db":
+            return [
+                *([] if self.databases else ["needs at least one database"]),
+                *(["takes no paths"] if self.paths else []),
+            ]
+        return [
+            *([] if self.paths else ["needs at least one path"]),
+            *(["takes no databases"] if self.databases else []),
+        ]
+
+
+@dataclass
+class StorageConfig:
+    """SFTP storage as reached FROM the web server (restic runs there)."""
+
+    host: str
+    user: str
+    base_path: str
+    port: int = 22
+    identity: str | None = None  # private key path on the web server
+
+    def validate(self) -> None:
+        v.hostname(self.host)
+        v.unix_user(self.user)
+        v.port(self.port)
+        v.remote_path(self.base_path)
+        if self.identity:
+            v.remote_abs_path(self.identity)
+
+
+@dataclass
+class ServerConfig:
+    label: str
+    ssh_host: str  # "localhost" runs everything on this machine without ssh
+    secrets_dir: str  # absolute dir on the server for 0600 my.cnf and restic password files
+    storage: StorageConfig
+    ssh_user: str | None = None
+    use_ssh_config: bool = False  # ssh_host is the user's own ~/.ssh/config alias; no managed block
+    ssh_port: int = 22
+    ssh_identity: str | None = None  # local private key for admin box -> server
+    db_login: bool = False  # my.cnf with the MariaDB admin login was written to secrets_dir
+    repos: dict[str, RepoConfig] = field(default_factory=dict)
+
+    @property
+    def is_local(self) -> bool:
+        return self.ssh_host == "localhost"
+
+    @property
+    def ssh_target(self) -> str:
+        from .sshconfig import host_alias
+
+        return self.ssh_host if self.use_ssh_config else host_alias(self.label)
+
+    @property
+    def mycnf_path(self) -> str:
+        return f"{self.secrets_dir}/my.cnf"
+
+    def password_path(self, repo: RepoConfig) -> str:
+        return f"{self.secrets_dir}/{repo.name}.pass"
+
+    def repository(self, repo: RepoConfig) -> str:
+        from .sshconfig import storage_alias
+
+        return f"sftp:{storage_alias(self.label)}:{self.storage.base_path}/{self.label}/{repo.name}"
+
+    def repo(self, name: str) -> RepoConfig:
+        try:
+            return self.repos[name]
+        except KeyError:
+            known = ", ".join(sorted(self.repos)) or "none"
+            raise ConfigError(
+                f"unknown repo {name!r} on server {self.label} (configured: {known})"
+            ) from None
+
+    def validate(self) -> None:
+        v.label(self.label)
+        v.hostname(self.ssh_host)
+        if self.ssh_user:
+            v.unix_user(self.ssh_user)
+        elif not self.use_ssh_config and not self.is_local:
+            raise v.ValidationError("ssh_user is required unless use_ssh_config is set")
+        v.port(self.ssh_port)
+        v.remote_abs_path(self.secrets_dir)
+        if self.ssh_identity:
+            v.abs_path(self.ssh_identity)
+        self.storage.validate()
+
+
+@dataclass
+class Config:
+    servers: dict[str, ServerConfig] = field(default_factory=dict)
+
+    def server(self, label: str) -> ServerConfig:
+        try:
+            return self.servers[label]
+        except KeyError:
+            known = ", ".join(sorted(self.servers)) or "none"
+            raise ConfigError(f"unknown server {label!r} (configured: {known})") from None
+
+
+def _drop_none(d: Any) -> Any:
+    if isinstance(d, dict):
+        return {k: _drop_none(x) for k, x in d.items() if x is not None}
+    return d
+
+
+def from_dict(data: dict[str, Any], source: str) -> Config:
+    data = dict(data)
+    if data.pop("version", None) != VERSION:
+        raise ConfigError(
+            f"{source}: v1 config detected (expected version = {VERSION}); "
+            "move it aside and re-run 'ltsbu discover <host>'"
+        )
+    try:
+        cfg = Config()
+        for label, raw in data.pop("servers", {}).items():
+            raw = dict(raw)
+            storage = StorageConfig(**raw.pop("storage", {}))
+            repos = {}
+            for name, r in raw.pop("repos", {}).items():
+                r = dict(r)
+                repos[name] = RepoConfig(
+                    name=name,
+                    schedule=Schedule(**r.pop("schedule", {})),
+                    keep=KeepPolicy(**r.pop("keep", {})),
+                    **r,
+                )
+            cfg.servers[label] = ServerConfig(label=label, storage=storage, repos=repos, **raw)
+    except TypeError as e:
+        raise ConfigError(f"{source}: unexpected or missing key: {e}") from None
+    if data:
+        raise ConfigError(f"{source}: unexpected top-level key(s): {', '.join(sorted(data))}")
+    return cfg
+
+
+def to_dict(cfg: Config) -> dict[str, Any]:
+    data: dict[str, Any] = {"version": VERSION, "servers": {}}
+    for label, server in sorted(cfg.servers.items()):
+        d = asdict(server)
+        d.pop("label")
+        for r in d["repos"].values():
+            r.pop("name")
+        d["repos"] = dict(sorted(d["repos"].items()))
+        data["servers"][label] = d
+    return dict(_drop_none(data))
+
+
+def parse_toml(text: str, source: str) -> dict[str, Any]:
+    try:
+        return tomllib.loads(text)
+    except tomllib.TOMLDecodeError as e:
+        raise ConfigError(f"{source}: invalid TOML: {e}") from None
+
+
+def load(path: Path) -> Config:
+    if not path.exists():
+        return Config()
+    return from_dict(parse_toml(path.read_text(), str(path)), str(path))
+
+
+def save(cfg: Config, path: Path) -> None:
+    tmp = path.with_suffix(".tmp")
+    write_secret(tmp, tomli_w.dumps(to_dict(cfg)))
+    os.replace(tmp, path)
+
+
+def write_secret(path: Path, content: str) -> None:
+    """Create/overwrite a secret file with 0600 from the start (no world-readable window)."""
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as fh:
+        fh.write(content)
+    os.chmod(path, 0o600)
+
+
+def mycnf_text(user: str, password: str) -> str:
+    def esc(s: str) -> str:
+        return s.replace("\\", "\\\\").replace('"', '\\"')
+
+    return f'[client]\nuser="{esc(user)}"\npassword="{esc(password)}"\nhost=localhost\n'
+
+
+def _perm_problem(p: Path, what: str) -> str | None:
+    if not p.exists():
+        return f"{what} missing: {p}"
+    if stat.S_IMODE(p.stat().st_mode) & 0o077:
+        return f"{what} {p} is accessible by group/others (chmod 600)"
+    return None
+
+
+def lint(cfg: Config, check_files: bool = True) -> list[str]:
+    """Validate all values; optionally check local files exist and secrets are 0600.
+    Server-side files are checked by doctor (needs ssh)."""
+    problems: list[str] = []
+    for label, server in sorted(cfg.servers.items()):
+        try:
+            server.validate()
+        except v.ValidationError as e:
+            problems.append(f"server {label}: {e}")
+            continue
+        if check_files and server.ssh_identity and not Path(server.ssh_identity).is_file():
+            problems.append(f"server {label}: ssh identity missing: {server.ssh_identity}")
+        for name, repo in sorted(server.repos.items()):
+            where = f"server {label} repo {name}"
+            try:
+                repo.validate()
+            except v.ValidationError as e:
+                problems.append(f"{where}: {e}")
+                continue
+            problems += [f"{where}: {repo.kind} repo {p}" for p in repo.kind_problems()]
+            if repo.kind == "db" and not server.db_login:
+                problems.append(f"{where}: no MariaDB login on the server; re-run 'ltsbu discover'")
+            if check_files and (
+                msg := _perm_problem(Path(repo.password_file), f"{where}: password file")
+            ):
+                problems.append(msg)
+    return problems

lts_backup_cli/doctor.py

@@ -0,0 +1,278 @@
+"""Health checks (Strategy): each check is a callable returning CheckResults.
+
+Remote checks run through the same SshRunner as backups; servers that fail the login
+check are skipped by the others (see _reachable)."""
+
+from __future__ import annotations
+
+import getpass
+import shutil
+import socket
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+from . import config as c
+from . import schedule, services, sshconfig
+from .mariadb import MariaDBClient, probe_binaries
+from .runner import Runner
+
+OK, WARN, FAIL = "ok", "warn", "fail"
+
+# Constant script; the binary names travel as positional args.
+_WHICH = 'for n in "$@"; do command -v "$n" && exit 0; done; exit 1'
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    name: str
+    status: str
+    detail: str = ""
+
+
+@dataclass
+class Context:
+    runner: Runner  # local; remote checks wrap it per server
+    cfg: c.Config
+    config_path: Path
+    ssh_config_path: Path
+    servers: list[c.ServerConfig]
+    units_dir: Path
+    user_units: bool
+    timeout: float = 5.0
+    login: dict[str, bool] = field(default_factory=dict)  # server label -> ssh login ok
+
+
+Check = Callable[[Context], Iterable[CheckResult]]
+
+
+def _login(ctx: Context, server: c.ServerConfig) -> tuple[bool, str]:
+    res = services.runner_for(ctx.runner, server).run(
+        ["true"], check=False, mutating=False, timeout=ctx.timeout * 6
+    )
+    ctx.login[server.label] = res.returncode == 0
+    return res.returncode == 0, res.stderr.strip()[-300:]
+
+
+def _reachable(ctx: Context) -> Iterator[tuple[c.ServerConfig, Runner]]:
+    """Servers we can log in to (one ssh attempt per server per doctor run)."""
+    for server in ctx.servers:
+        if server.label not in ctx.login:
+            _login(ctx, server)
+        if ctx.login[server.label]:
+            yield server, services.runner_for(ctx.runner, server)
+
+
+def check_local_binaries(ctx: Context) -> Iterable[CheckResult]:
+    for name, required in (("ssh", True), ("systemctl", False)):
+        found = shutil.which(name)
+        status = OK if found else (FAIL if required else WARN)
+        yield CheckResult(f"local binary {name}", status, found or "not found in PATH")
+
+
+def check_config(ctx: Context) -> Iterable[CheckResult]:
+    if not ctx.config_path.exists():
+        yield CheckResult(
+            "config", FAIL, f"{ctx.config_path} not found; run 'ltsbu discover <host>'"
+        )
+        return
+    problems = c.lint(ctx.cfg)
+    yield CheckResult(
+        "config lint", FAIL if problems else OK, "; ".join(problems) or str(ctx.config_path)
+    )
+
+
+def check_ssh_config(ctx: Context) -> Iterable[CheckResult]:
+    text = sshconfig.read(ctx.ssh_config_path)
+    problems = sshconfig.lint(text)
+    yield CheckResult(
+        "ssh config lint", FAIL if problems else OK, "; ".join(problems) or str(ctx.ssh_config_path)
+    )
+    for s in ctx.servers:
+        if not s.is_local and not s.use_ssh_config and not sshconfig.has_block(text, s.label):
+            yield CheckResult(
+                f"[{s.label}] ssh block", FAIL, f"no ltsbu:{s.label} block; re-run 'ltsbu discover'"
+            )
+
+
+def check_network(ctx: Context) -> Iterable[CheckResult]:
+    for s in ctx.servers:
+        if s.is_local or s.use_ssh_config:  # the user's alias may not be a resolvable name
+            continue
+        name = f"[{s.label}]"
+        try:
+            addrs = socket.getaddrinfo(s.ssh_host, s.ssh_port, type=socket.SOCK_STREAM)
+        except socket.gaierror as e:
+            yield CheckResult(f"{name} dns {s.ssh_host}", FAIL, str(e))
+            continue
+        yield CheckResult(f"{name} dns {s.ssh_host}", OK, str(addrs[0][4][0]))
+        try:
+            with socket.create_connection((s.ssh_host, s.ssh_port), timeout=ctx.timeout):
+                pass
+            yield CheckResult(f"{name} tcp {s.ssh_host}:{s.ssh_port}", OK)
+        except OSError as e:
+            yield CheckResult(f"{name} tcp {s.ssh_host}:{s.ssh_port}", FAIL, str(e))
+
+
+def check_server_login(ctx: Context) -> Iterable[CheckResult]:
+    for s in ctx.servers:
+        ok, err = _login(ctx, s)
+        yield CheckResult(f"[{s.label}] ssh login", OK if ok else FAIL, err or s.ssh_target)
+
+
+def check_server_binaries(ctx: Context) -> Iterable[CheckResult]:
+    for s, r in _reachable(ctx):
+        needs_db = any(repo.kind == "db" for repo in s.repos.values())
+        for names, required in (
+            (("restic",), True),
+            (("mariadb", "mysql"), needs_db),
+            (("mariadb-dump", "mysqldump"), needs_db),
+        ):
+            res = r.run(["sh", "-c", _WHICH, "sh", *names], check=False, mutating=False)
+            found = res.returncode == 0
+            yield CheckResult(
+                f"[{s.label}] remote binary {'/'.join(names)}",
+                OK if found else (FAIL if required else WARN),
+                res.stdout.strip() if found else "not found in PATH on the server",
+            )
+
+
+def check_server_paths(ctx: Context) -> Iterable[CheckResult]:
+    for s, r in _reachable(ctx):
+        for repo in s.repos.values():
+            for path in repo.paths:
+                ok = r.run(["test", "-d", path], check=False, mutating=False).returncode == 0
+                yield CheckResult(
+                    f"[{s.label}/{repo.name}] path {path}",
+                    OK if ok else FAIL,
+                    "" if ok else "not a directory on the server",
+                )
+
+
+def check_server_database(ctx: Context) -> Iterable[CheckResult]:
+    for s, r in _reachable(ctx):
+        dbs = sorted(
+            {d for repo in s.repos.values() if repo.kind == "db" for d in repo.databases},
+            reverse=True,
+        )
+        if not dbs:
+            continue
+        if not s.db_login:
+            yield CheckResult(
+                f"[{s.label}] mariadb login", FAIL, "no login configured; run 'ltsbu discover'"
+            )
+            continue
+        mode = r.run(["stat", "-c", "%a", s.mycnf_path], check=False, mutating=False).stdout.strip()
+        yield CheckResult(
+            f"[{s.label}] my.cnf permissions",
+            OK if mode == "600" else FAIL,
+            f"{s.mycnf_path} mode {mode or 'missing'}",
+        )
+        db = MariaDBClient(r, s.mycnf_path, probe_binaries(r))
+        if not db.ping():
+            yield CheckResult(
+                f"[{s.label}] mariadb login",
+                FAIL,
+                "cannot connect with the saved login; re-run 'ltsbu discover'",
+            )
+            continue
+        yield CheckResult(f"[{s.label}] mariadb login", OK)
+        present = set(db.list_databases())
+        for name in dbs:
+            yield CheckResult(
+                f"[{s.label}] database {name}",
+                OK if name in present else FAIL,
+                "" if name in present else "database not found",
+            )
+
+
+def check_storage(ctx: Context) -> Iterable[CheckResult]:
+    for s, r in _reachable(ctx):
+        alias = sshconfig.storage_alias(s.label)
+        res = r.run(
+            [
+                "ssh",
+                "-o",
+                "BatchMode=yes",
+                "-o",
+                f"ConnectTimeout={int(ctx.timeout)}",
+                alias,
+                "true",
+            ],
+            check=False,
+            mutating=False,
+            timeout=ctx.timeout * 6,
+        )
+        yield CheckResult(
+            f"[{s.label}] storage ssh {alias}",
+            OK if res.returncode == 0 else FAIL,
+            res.stderr.strip()[-300:],
+        )
+        if res.returncode != 0:
+            continue
+        for repo in s.repos.values():
+            ok = services.restic_for(r, s, repo).is_initialized()
+            yield CheckResult(
+                f"[{s.label}/{repo.name}] restic repository", OK if ok else FAIL, s.repository(repo)
+            )
+
+
+def check_timers(ctx: Context) -> Iterable[CheckResult]:
+    for s in ctx.servers:
+        for repo in s.repos.values():
+            base = schedule.unit_base(s.label, repo.name)
+            timers = [f"{base}.timer", f"{base}-weekly.timer"]
+            missing = [t for t in timers if not (ctx.units_dir / t).is_file()]
+            if missing:
+                yield CheckResult(
+                    f"[{s.label}/{repo.name}] timers",
+                    FAIL,
+                    f"missing {', '.join(missing)}; re-run 'ltsbu discover'",
+                )
+                continue
+            res = ctx.runner.run(
+                ["systemctl", *(["--user"] if ctx.user_units else []), "is-enabled", *timers],
+                check=False,
+                mutating=False,
+            )
+            enabled = res.returncode == 0
+            yield CheckResult(
+                f"[{s.label}/{repo.name}] timers",
+                OK if enabled else FAIL,
+                res.stdout.strip().replace("\n", ", "),
+            )
+    if ctx.user_units and any(s.repos for s in ctx.servers):
+        res = ctx.runner.run(
+            ["loginctl", "show-user", getpass.getuser(), "-p", "Linger"],
+            check=False,
+            mutating=False,
+        )
+        if "Linger=yes" not in res.stdout:
+            yield CheckResult(
+                "systemd linger", WARN, "user timers stop at logout; run 'loginctl enable-linger'"
+            )
+
+
+CHECKS: list[Check] = [
+    check_local_binaries,
+    check_config,
+    check_ssh_config,
+    check_network,
+    check_server_login,
+    check_server_binaries,
+    check_server_paths,
+    check_server_database,
+    check_storage,
+    check_timers,
+]
+
+
+def run(ctx: Context, checks: list[Check] | None = None) -> list[CheckResult]:
+    results: list[CheckResult] = []
+    for check in checks or CHECKS:
+        try:
+            results.extend(check(ctx))
+        except Exception as e:  # a broken check must not hide the others
+            results.append(CheckResult(check.__name__, FAIL, f"check crashed: {e}"))
+    return results