close1 0.7.1__py3-none-any.whl

close1/__init__.py

@@ -0,0 +1,3 @@
+"""close1 — simple backups from servers over SSH."""
+
+__version__ = "0.7.1"

close1/__main__.py

@@ -0,0 +1,3 @@
+from close1.cli import main
+
+raise SystemExit(main())

close1/backup.py

@@ -0,0 +1,214 @@
+"""Backing up a single server."""
+
+from __future__ import annotations
+
+import datetime as dt
+import logging
+import posixpath
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from close1.config import FileItem, HostConfig
+from close1.messages import t
+from close1.rotate import to_delete
+from close1.ssh import Remote, RemoteError, remote_path
+
+log = logging.getLogger("close1")
+
+_DATE_RE = re.compile(r"\$\{DATE\}|\$DATE\b")
+ARCHIVE_EXT = {"tar.gz": ".tar.gz", "zip": ".zip"}
+
+
+class BackupError(Exception):
+    pass
+
+
+def substitute(text: str, date: str) -> str:
+    """$DATE and ${DATE} -> 2026-12-31."""
+    return _DATE_RE.sub(date, text)
+
+
+def archive_type(name: str | None, default: str) -> str:
+    """Archive format for a directory: from the explicit name's extension, else the compress option."""
+    if name:
+        if name.endswith(".zip"):
+            return "zip"
+        if name.endswith((".tar.gz", ".tgz")):
+            return "tar.gz"
+    return default
+
+
+@dataclass
+class Plan:
+    """What to copy and under which local name."""
+
+    remote: str
+    local: str
+    archive: str | None  # None for a regular file
+
+
+def plan_files(items: list[tuple[FileItem, bool]], compress: str, reserved: set[str]) -> list[Plan]:
+    """Choose local names. items are (item, is_dir); reserved are names taken by stdout.
+
+    Explicit names are claimed first; the rest get the basename, or the full path joined with '-' on collision.
+    """
+    used = set(reserved)
+    locals_: list[str | None] = []
+    for item, is_dir in items:
+        local = None
+        if item.name:
+            local = item.name
+            archive = archive_type(item.name, compress) if is_dir else None
+            if archive and not local.endswith((".zip", ".tar.gz", ".tgz")):
+                local += ARCHIVE_EXT[archive]
+            if local in used:
+                raise BackupError(t("name_collision", path=item.remote))
+            used.add(local)
+        locals_.append(local)
+
+    plans = []
+    for (item, is_dir), local in zip(items, locals_):
+        archive = archive_type(item.name, compress) if is_dir else None
+        if local is None:
+            ext = ARCHIVE_EXT[archive] if archive else ""
+            stripped = item.remote.strip("/")
+            base = posixpath.basename(stripped) or "root"
+            full = stripped.replace("/", "-") or "root"
+            local = next((c + ext for c in (base, full) if c + ext not in used), None)
+            if local is None:
+                raise BackupError(t("name_collision", path=item.remote))
+            used.add(local)
+        plans.append(Plan(remote=item.remote, local=local, archive=archive))
+    return plans
+
+
+def remote_kind(remote: Remote, path: str) -> str:
+    q = remote_path(path)
+    out = remote.run(f"if [ -d {q} ]; then echo dir; elif [ -e {q} ]; then echo file; else echo none; fi", retry=True)
+    return out.strip()
+
+
+def _require_tool(remote: Remote, tool: str) -> None:
+    if remote.run(f"command -v {tool} >/dev/null 2>&1 && echo yes || echo no", retry=True).strip() != "yes":
+        raise BackupError(t("tool_missing", tool=tool))
+
+
+def fetch(remote: Remote, plan: Plan, target: Path) -> None:
+    q = remote_path(plan.remote)
+    if plan.archive == "tar.gz":
+        cmd = f"tar -C {q} -czf - ."
+    elif plan.archive == "zip":
+        cmd = f"cd {q} && zip -qr - ."
+    else:
+        cmd = f"cat -- {q}"
+    with open(target, "wb") as f:
+        remote.run(cmd, stdout=f, retry=True)
+
+
+class HostBackup:
+    def __init__(self, host: HostConfig, agent_sock: str | None, force: bool = False,
+                 today: dt.date | None = None):
+        self.host = host
+        self.force = force
+        self.today = today or dt.date.today()
+        self.date = self.today.isoformat()
+        self.remote = Remote(host, agent_sock)
+        self.host_dir = host.dest / host.name
+        self.final = self.host_dir / self.date
+        self.partial = self.host_dir / f"{self.date}.partial"
+
+    def run(self) -> bool:
+        """True if the backup was made or is not needed, False on error."""
+        name = self.host.section
+        if self.final.exists() and not self.force:
+            log.info(t("already_done", name=name, date=self.date))
+            return True
+        if self.host.ssh_key and not self.remote.agent_sock:
+            log.warning(t("key_not_found", name=name, fp=self.host.ssh_key))
+            return True  # not an error: the key may be loaded later
+        with self.remote:
+            try:
+                self.remote.check()
+            except RemoteError as e:
+                log.warning(t("unreachable", name=name, error=e.stderr or e.code))
+                return True  # not an error: retry on the next run
+
+            try:
+                self._backup()
+            except (RemoteError, BackupError, OSError) as e:
+                log.error(t("failed", name=name, error=e))
+                return False
+        log.info(t("done", name=name, path=self.final))
+        self._rotate()
+        return True
+
+    def _run_stage(self, stage: str, commands: list[str]) -> None:
+        for cmd in commands:
+            cmd = substitute(cmd, self.date)
+            log.info(t("run_cmd", name=self.host.section, stage=stage, cmd=cmd))
+            out = self.remote.run(cmd)
+            if out.strip():
+                log.debug(out.rstrip())
+
+    def _backup(self) -> None:
+        h = self.host
+        if self.partial.exists():
+            shutil.rmtree(self.partial)
+        self.partial.mkdir(parents=True)
+        log.info(t("start", name=h.section, path=self.final))
+
+        try:
+            self._run_stage("pre", h.pre)
+            self._copy_files()
+            for local, cmd in h.stdout.items():
+                cmd = substitute(cmd, self.date)
+                log.info(t("run_cmd", name=h.section, stage="stdout", cmd=f"{cmd} > {local}"))
+                with open(self.partial / local, "wb") as f:
+                    self.remote.run(cmd, stdout=f)
+        except BaseException:
+            # run post even on failure, e.g. to turn maintenance mode off
+            try:
+                self._run_stage("post", h.post)
+            except RemoteError as e:
+                log.error(t("failed", name=h.section, error=e))
+            raise
+        self._run_stage("post", h.post)
+
+        if self.final.exists():
+            old = self.host_dir / f"{self.date}.old"
+            if old.exists():
+                shutil.rmtree(old)
+            self.final.rename(old)
+            self.partial.rename(self.final)
+            shutil.rmtree(old)
+        else:
+            self.partial.rename(self.final)
+
+    def _copy_files(self) -> None:
+        h = self.host
+        items = []
+        for item in h.files:
+            path = substitute(item.remote, self.date)
+            kind = remote_kind(self.remote, path)
+            if kind == "none":
+                raise BackupError(t("remote_missing", path=path))
+            items.append((FileItem(remote=path, name=item.name), kind == "dir"))
+
+        tools = {"tar" if a == "tar.gz" else "zip"
+                 for a in (archive_type(i.name, h.compress) for i, d in items if d)}
+        for tool in sorted(tools):
+            _require_tool(self.remote, tool)
+
+        for plan in plan_files(items, h.compress, set(h.stdout)):
+            log.info(t("copy", name=h.section, remote=plan.remote, local=plan.local))
+            fetch(self.remote, plan, self.partial / plan.local)
+
+    def _rotate(self) -> None:
+        for p in self.host_dir.glob("*.partial"):
+            if p.is_dir():
+                shutil.rmtree(p)
+        for p in to_delete(self.host_dir, self.host.keep):
+            log.info(t("rotate_delete", name=self.host.section, path=p))
+            shutil.rmtree(p)

close1/cli.py

@@ -0,0 +1,168 @@
+"""close1 command line."""
+
+from __future__ import annotations
+
+import argparse
+import fcntl
+import logging
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from close1 import __version__
+from close1.backup import HostBackup
+from close1.config import Config, ConfigError, config_search_paths, find_config, is_root, load_config
+from close1.messages import t
+from close1.ssh import Remote, RemoteError, find_agent, list_agents
+
+log = logging.getLogger("close1")
+
+
+def default_log_path() -> Path:
+    if is_root():
+        return Path("/var/log/close1.log")
+    base = os.environ.get("XDG_STATE_HOME") or "~/.local/state"
+    return Path(base).expanduser() / "close1" / "close1.log"
+
+
+def setup_logging(log_path: Path, verbose: bool) -> None:
+    log.setLevel(logging.DEBUG)
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    fh = logging.FileHandler(log_path, encoding="utf-8")
+    fh.setLevel(logging.DEBUG if verbose else logging.INFO)
+    fh.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
+    log.addHandler(fh)
+
+    # Under cron (no tty) only errors go to stderr, so cron mails only on real problems.
+    sh = logging.StreamHandler(sys.stderr)
+    if verbose:
+        sh.setLevel(logging.DEBUG)
+    else:
+        sh.setLevel(logging.WARNING if sys.stderr.isatty() else logging.ERROR)
+    sh.setFormatter(logging.Formatter("%(levelname)s %(message)s"))
+    log.addHandler(sh)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="close1", description="Back up files from servers over SSH")
+    p.add_argument("hosts", nargs="*", metavar="HOST", help="config sections to back up (default: all), or 'log' to show the log")
+    p.add_argument("-c", "--config", type=Path, help="config file (default: first of $CLOSE1_CONFIG, ~/.config/close1/close1.yml, /etc/close1.yml)")
+    p.add_argument("-f", "--force", action="store_true", help="overwrite today's backup")
+    p.add_argument("-v", "--verbose", action="store_true", help="verbose output")
+    p.add_argument("--check", action="store_true", help="check the SSH agent and host reachability, copy nothing")
+    p.add_argument("--version", action="version", version=f"close1 {__version__}")
+    return p
+
+
+def select_hosts(cfg: Config, names: list[str]):
+    if not names:
+        return cfg.hosts
+    by_name = {h.section: h for h in cfg.hosts}
+    missing = [n for n in names if n not in by_name]
+    if missing:
+        raise ConfigError(t("unknown_host", name=", ".join(missing)))
+    return [by_name[n] for n in names]
+
+
+def check(cfg: Config, hosts, sock: str | None, log_path: Path) -> int:
+    print(t("check_header", version=__version__, config=cfg.path, log=log_path))
+    agents = list_agents(cfg.ssh_auth_sock)
+    for agent_sock, keys in agents:
+        print(t("agent_found", sock=agent_sock, count=len(keys)))
+        for k in keys:
+            print("  " + k)
+    if not agents:
+        print(t("agent_not_found"))
+    rc = 0
+    for h in hosts:
+        host_sock = sock
+        if h.ssh_key:
+            host_sock = find_agent(cfg.ssh_auth_sock, h.ssh_key)[0]
+            if not host_sock:
+                print(t("check_fail", name=h.section, error=t("check_key_missing", fp=h.ssh_key)))
+                rc = 1
+                continue
+            print(t("check_agent", name=h.section, sock=host_sock))
+        try:
+            with Remote(h, host_sock) as remote:
+                remote.check()
+            print(t("check_ok", name=h.section))
+        except RemoteError as e:
+            print(t("check_fail", name=h.section, error=e.stderr or e.code))
+            rc = 1
+    return rc
+
+
+def show_log(log_path: Path, verbose: bool) -> int:
+    """close1 log: print the log file (with -v, first a '# path' line)."""
+    if verbose:
+        print(f"# {log_path}", flush=True)
+    try:
+        with open(log_path, "rb") as f:
+            shutil.copyfileobj(f, sys.stdout.buffer)
+        sys.stdout.flush()
+    except FileNotFoundError:
+        print(t("log_missing", path=log_path), file=sys.stderr)
+        return 1
+    except BrokenPipeError:  # e.g. close1 log | head
+        sys.stderr.close()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    log_cmd = args.hosts == ["log"]
+    if log_cmd:
+        args.hosts = []
+
+    if args.config:
+        cfg_path = args.config
+        if not cfg_path.is_file():
+            print(t("config_not_found", path=cfg_path), file=sys.stderr)
+            return 2
+    else:
+        cfg_path = find_config()
+        if cfg_path is None:
+            paths = "\n".join(f"  {p}" for p in config_search_paths())
+            print(t("config_not_found_search", paths=paths), file=sys.stderr)
+            return 2
+    try:
+        cfg = load_config(cfg_path)
+        hosts = select_hosts(cfg, args.hosts)
+    except ConfigError as e:
+        print(t("config_error", path=cfg_path, error=e), file=sys.stderr)
+        return 2
+
+    log_path = Path(cfg.log).expanduser() if cfg.log else default_log_path()
+    if log_cmd:
+        return show_log(log_path, args.verbose)
+    setup_logging(log_path, args.verbose)
+    log.debug(t("log_file", version=__version__, config=cfg_path, path=log_path))
+
+    sock, keys = find_agent(cfg.ssh_auth_sock)
+    if args.check:
+        return check(cfg, hosts, sock, log_path)
+
+    lock_path = log_path.with_suffix(".lock")
+    with open(lock_path, "w") as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            log.info(t("already_running", path=lock_path))
+            return 0
+
+        if sock:
+            log.debug(t("agent_found", sock=sock, count=len(keys)))
+        else:
+            log.warning(t("agent_not_found"))
+
+        ok = True
+        for h in hosts:
+            host_sock = find_agent(cfg.ssh_auth_sock, h.ssh_key)[0] if h.ssh_key else sock
+            ok = HostBackup(h, host_sock, force=args.force).run() and ok
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

close1/config.py

@@ -0,0 +1,271 @@
+"""Loading and validating the close1 config."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+DEFAULT_SECTION = "_default"
+COMPRESS_TYPES = ("tar.gz", "zip")
+
+# Allowed both in _default and in a host section.
+COMMON_KEYS = {
+    "dest", "compress", "keep", "user", "port", "ssh_options", "ssh_key",
+    "connect_timeout", "retries", "retry_delay",
+}
+# Only in _default.
+GLOBAL_KEYS = {"ssh_auth_sock", "log"}
+# Only in a host section.
+HOST_KEYS = {"name", "pre", "files", "stdout", "post"}
+
+BUILTIN_DEFAULTS: dict[str, Any] = {
+    "dest": "~/backups",
+    "compress": "tar.gz",
+    "keep": 7,
+    "connect_timeout": 30,
+    "retries": 3,
+    "retry_delay": 10,
+}
+
+_HOST_RE = re.compile(r"^(?:(?P<user>[^@:\s]+)@)?(?P<host>[^@:\s]+)(?::(?P<port>\d+))?$")
+
+
+class ConfigError(Exception):
+    pass
+
+
+@dataclass
+class FileItem:
+    remote: str
+    name: str | None = None  # explicit local name
+
+
+@dataclass
+class HostConfig:
+    section: str
+    name: str  # directory name under dest
+    host: str
+    user: str | None
+    port: int | None
+    ssh_options: list[str]
+    ssh_key: str | None  # SHA256 fingerprint of the key to look for in agents
+    connect_timeout: int
+    retries: int
+    retry_delay: float
+    dest: Path
+    compress: str
+    keep: int  # how many latest backups to keep
+    pre: list[str] = field(default_factory=list)
+    files: list[FileItem] = field(default_factory=list)
+    stdout: dict[str, str] = field(default_factory=dict)
+    post: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Config:
+    path: Path
+    hosts: list[HostConfig]
+    ssh_auth_sock: str | None = None
+    log: str | None = None
+
+
+def is_root() -> bool:
+    return os.geteuid() == 0
+
+
+SYSTEM_CONFIG = Path("/etc/close1.yml")
+
+
+def config_search_paths() -> list[Path]:
+    """Config search order: $CLOSE1_CONFIG, ~/.config/close1/close1.yml, /etc/close1.yml."""
+    paths = []
+    env = os.environ.get("CLOSE1_CONFIG")
+    if env:
+        paths.append(Path(env).expanduser())
+    base = os.environ.get("XDG_CONFIG_HOME") or "~/.config"
+    paths.append(Path(base).expanduser() / "close1" / "close1.yml")
+    paths.append(SYSTEM_CONFIG)
+    return paths
+
+
+def find_config() -> Path | None:
+    """The first existing config from config_search_paths()."""
+    return next((p for p in config_search_paths() if p.is_file()), None)
+
+
+def parse_host_key(key: str) -> tuple[str | None, str, int | None]:
+    """'backup@bot:12234' -> ('backup', 'bot', 12234)."""
+    m = _HOST_RE.match(key)
+    if not m:
+        raise ConfigError(f"invalid host name: {key!r}")
+    port = int(m["port"]) if m["port"] else None
+    return m["user"], m["host"], port
+
+
+def parse_keep(value: Any) -> int:
+    """keep: how many latest backups to keep (a whole number >= 1)."""
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise ConfigError(f"keep: expected a whole number >= 1, got {value!r}")
+    return value
+
+
+def check_local_name(name: Any, where: str) -> str:
+    if not isinstance(name, str) or not name or "/" in name or name in (".", ".."):
+        raise ConfigError(f"{where}: invalid local name {name!r}")
+    return name
+
+
+def _str_list(value: Any, where: str) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+        raise ConfigError(f"{where}: expected a list of strings")
+    return value
+
+
+def _parse_files(value: Any, where: str) -> list[FileItem]:
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        raise ConfigError(f"{where}: expected a list")
+    items = []
+    for entry in value:
+        if isinstance(entry, str):
+            items.append(FileItem(remote=entry))
+        elif isinstance(entry, dict) and len(entry) == 1:
+            # "local name: remote path" — the key is the local name, as in stdout
+            ((name, remote),) = entry.items()
+            if isinstance(name, str) and "/" in name and isinstance(remote, str) and "/" not in remote:
+                raise ConfigError(f"{where}: use 'name: /path' (got '{name}: {remote}')")
+            if not isinstance(remote, str) or not remote:
+                raise ConfigError(f"{where}: invalid path {remote!r}")
+            items.append(FileItem(remote=remote, name=check_local_name(name, where)))
+        else:
+            raise ConfigError(f"{where}: expected a path or 'name: path', got {entry!r}")
+    return items
+
+
+def _parse_stdout(value: Any, where: str) -> dict[str, str]:
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ConfigError(f"{where}: expected a mapping of 'file_name: command'")
+    result = {}
+    for name, cmd in value.items():
+        check_local_name(name, where)
+        if not isinstance(cmd, str) or not cmd.strip():
+            raise ConfigError(f"{where}.{name}: expected a command")
+        result[name] = cmd
+    return result
+
+
+def _build_host(section: str, raw: dict[str, Any], defaults: dict[str, Any]) -> HostConfig:
+    unknown = set(raw) - COMMON_KEYS - HOST_KEYS
+    if unknown:
+        raise ConfigError(f"{section}: unknown options: {', '.join(sorted(unknown))}")
+    opts = {**BUILTIN_DEFAULTS, **defaults, **raw}
+
+    user, host, port = parse_host_key(section)
+    user = opts.get("user") if "user" in raw or user is None else user
+    if "port" in raw or port is None:
+        port = opts.get("port")
+    if port is not None and not isinstance(port, int):
+        raise ConfigError(f"{section}.port: expected a number")
+
+    ssh_key = opts.get("ssh_key")
+    if ssh_key is not None and not (isinstance(ssh_key, str) and ssh_key.startswith("SHA256:")):
+        raise ConfigError(f"{section}.ssh_key: expected a fingerprint like SHA256:..., got {ssh_key!r}")
+
+    for opt, minimum in (("connect_timeout", 1), ("retries", 0), ("retry_delay", 0)):
+        value = opts[opt]
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or value < minimum:
+            raise ConfigError(f"{section}.{opt}: expected a number >= {minimum}, got {value!r}")
+    if not isinstance(opts["connect_timeout"], int) or not isinstance(opts["retries"], int):
+        raise ConfigError(f"{section}: connect_timeout and retries must be whole numbers")
+
+    compress = opts["compress"]
+    if compress not in COMPRESS_TYPES:
+        raise ConfigError(f"{section}.compress: expected {' | '.join(COMPRESS_TYPES)}, got {compress!r}")
+
+    hc = HostConfig(
+        section=section,
+        name=check_local_name(raw.get("name", host), f"{section}.name"),
+        host=host,
+        user=user,
+        port=port,
+        ssh_options=_str_list(opts.get("ssh_options"), f"{section}.ssh_options"),
+        ssh_key=ssh_key,
+        connect_timeout=opts["connect_timeout"],
+        retries=opts["retries"],
+        retry_delay=opts["retry_delay"],
+        dest=Path(str(opts["dest"])).expanduser(),
+        compress=compress,
+        keep=parse_keep(opts["keep"]),
+        pre=_str_list(raw.get("pre"), f"{section}.pre"),
+        files=_parse_files(raw.get("files"), f"{section}.files"),
+        stdout=_parse_stdout(raw.get("stdout"), f"{section}.stdout"),
+        post=_str_list(raw.get("post"), f"{section}.post"),
+    )
+
+    explicit = [f.name for f in hc.files if f.name] + list(hc.stdout)
+    dupes = {n for n in explicit if explicit.count(n) > 1}
+    if dupes:
+        raise ConfigError(f"{section}: duplicate local names: {', '.join(sorted(dupes))}")
+    return hc
+
+
+def parse_config(data: Any, path: Path) -> Config:
+    if data is None:
+        data = {}
+    if not isinstance(data, dict):
+        raise ConfigError("expected a mapping of sections")
+
+    defaults = data.get(DEFAULT_SECTION) or {}
+    if not isinstance(defaults, dict):
+        raise ConfigError(f"{DEFAULT_SECTION}: expected a mapping")
+    unknown = set(defaults) - COMMON_KEYS - GLOBAL_KEYS
+    if unknown:
+        raise ConfigError(f"{DEFAULT_SECTION}: unknown options: {', '.join(sorted(unknown))}")
+    host_defaults = {k: v for k, v in defaults.items() if k in COMMON_KEYS}
+
+    hosts = []
+    for section, raw in data.items():
+        if section == DEFAULT_SECTION:
+            continue
+        if raw is None:
+            raw = {}
+        if not isinstance(section, str) or not isinstance(raw, dict):
+            raise ConfigError(f"{section}: expected a mapping of options")
+        hosts.append(_build_host(section, raw, host_defaults))
+
+    seen: dict[tuple[Path, str], str] = {}
+    for h in hosts:
+        key = (h.dest, h.name)
+        if key in seen:
+            raise ConfigError(
+                f"sections {seen[key]!r} and {h.section!r} write to the same directory {h.name!r}, set 'name'"
+            )
+        seen[key] = h.section
+
+    return Config(
+        path=path,
+        hosts=hosts,
+        ssh_auth_sock=defaults.get("ssh_auth_sock"),
+        log=defaults.get("log"),
+    )
+
+
+def load_config(path: Path) -> Config:
+    with open(path, encoding="utf-8") as f:
+        try:
+            data = yaml.safe_load(f)
+        except yaml.YAMLError as e:
+            raise ConfigError(str(e)) from e
+    return parse_config(data, path)

close1/messages.py

@@ -0,0 +1,38 @@
+"""User-facing messages."""
+
+from __future__ import annotations
+
+MESSAGES: dict[str, str] = {
+    "config_not_found": "Config not found: {path}",
+    "config_not_found_search": "Config not found. Search order:\n{paths}\nCreate one (see close1-example.yml) or use -c",
+    "config_error": "Config error in {path}: {error}",
+    "unknown_host": "Host not found in config: {name}",
+    "log_file": "close1 {version}, config: {config}, log: {path}",
+    "log_missing": "No log yet: {path}",
+    "already_running": "close1 is already running (lock: {path}), exiting",
+    "agent_found": "SSH agent: {sock} (keys: {count})",
+    "agent_not_found": "No SSH agent with keys found, connections will most likely fail",
+    "key_not_found": "[{name}] key {fp} not found in any SSH agent, skipping",
+    "check_key_missing": "key {fp} not found in any SSH agent",
+    "check_agent": "  {name}: agent {sock}",
+    "retry": "[{name}] connection problem, retry {n}/{total} in {delay}s: {error}",
+    "already_done": "[{name}] backup for {date} already exists, skipping (use -f to overwrite)",
+    "unreachable": "[{name}] host unreachable or no key in agent, skipping: {error}",
+    "start": "[{name}] starting backup to {path}",
+    "run_cmd": "[{name}] {stage}: {cmd}",
+    "copy": "[{name}] {remote} -> {local}",
+    "done": "[{name}] backup finished: {path}",
+    "failed": "[{name}] backup failed: {error}",
+    "rotate_delete": "[{name}] rotation: removing {path}",
+    "cmd_failed": "command exited with code {code}: {cmd}: {stderr}",
+    "remote_missing": "no such file or directory on server: {path}",
+    "tool_missing": "{tool} not found on server",
+    "name_collision": "cannot find a unique local name for {path}",
+    "check_header": "close1 {version}, config: {config}, log: {log}",
+    "check_ok": "  {name}: OK",
+    "check_fail": "  {name}: FAIL: {error}",
+}
+
+
+def t(key: str, **kwargs: object) -> str:
+    return MESSAGES[key].format(**kwargs)

close1/rotate.py

@@ -0,0 +1,21 @@
+"""Backup rotation: keep the N latest backups."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+DATE_DIR_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def backup_dirs(host_dir: Path) -> list[Path]:
+    """Backup directories named YYYY-MM-DD, newest first."""
+    if not host_dir.is_dir():
+        return []
+    dirs = [p for p in host_dir.iterdir() if p.is_dir() and DATE_DIR_RE.match(p.name)]
+    return sorted(dirs, key=lambda p: p.name, reverse=True)
+
+
+def to_delete(host_dir: Path, keep: int) -> list[Path]:
+    """Backups beyond the `keep` latest ones, no matter how old they are."""
+    return backup_dirs(host_dir)[keep:]

close1/ssh.py

@@ -0,0 +1,199 @@
+"""SSH: agent discovery and running commands on a server via the system ssh."""
+
+from __future__ import annotations
+
+import logging
+import os
+import shlex
+import shutil
+import stat
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+from typing import IO
+
+from close1.config import HostConfig
+from close1.messages import t
+
+log = logging.getLogger("close1")
+
+# Always added: no interactive prompts (cron) and no agent forwarding to the backed-up server.
+BASE_OPTIONS = ["BatchMode=yes", "ForwardAgent=no"]
+
+# ssh exits with 255 on its own errors. These ones will not go away on retry.
+PERMANENT_ERRORS = (
+    "Permission denied",
+    "Host key verification failed",
+    "Could not resolve hostname",
+    "REMOTE HOST IDENTIFICATION HAS CHANGED",
+)
+
+
+class RemoteError(Exception):
+    """A remote command (or ssh itself) failed."""
+
+    def __init__(self, cmd: str, code: int, stderr: str):
+        super().__init__(cmd, code, stderr)
+        self.cmd, self.code, self.stderr = cmd, code, stderr
+
+    def __str__(self) -> str:
+        return t("cmd_failed", code=self.code, cmd=self.cmd, stderr=self.stderr)
+
+
+def is_connection_error(e: RemoteError) -> bool:
+    """A transient ssh connection problem (worth retrying)."""
+    return e.code == 255 and not any(m in e.stderr for m in PERMANENT_ERRORS)
+
+
+def agent_candidates() -> list[str]:
+    """Usual locations of the user's ssh-agent socket (cron does not pass SSH_AUTH_SOCK)."""
+    result = []
+    env = os.environ.get("SSH_AUTH_SOCK")
+    if env:
+        result.append(env)
+    run = Path(os.environ.get("XDG_RUNTIME_DIR") or f"/run/user/{os.getuid()}")
+    for rel in ("openssh_agent", "ssh-agent.socket", "gcr/ssh", "keyring/ssh", "gnupg/S.gpg-agent.ssh"):
+        p = str(run / rel)
+        if p not in result:
+            result.append(p)
+    return result
+
+
+def agent_keys(sock: str) -> list[str]:
+    """Keys in the agent (ssh-add -l output), or an empty list."""
+    try:
+        if not stat.S_ISSOCK(os.stat(sock).st_mode):
+            return []
+        r = subprocess.run(
+            ["ssh-add", "-l"],
+            env={**os.environ, "SSH_AUTH_SOCK": sock},
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return []
+    if r.returncode != 0:
+        return []
+    return [line for line in r.stdout.splitlines() if line.strip()]
+
+
+def has_key(keys: list[str], fingerprint: str) -> bool:
+    """Whether ssh-add -l lines contain the fingerprint (second field)."""
+    return any(len(line.split()) > 1 and line.split()[1] == fingerprint for line in keys)
+
+
+def list_agents(explicit: str | None = None) -> list[tuple[str, list[str]]]:
+    """Agent sockets that hold keys, with their keys, in search order."""
+    candidates = [os.path.expanduser(explicit)] if explicit else agent_candidates()
+    return [(sock, keys) for sock in candidates if (keys := agent_keys(sock))]
+
+
+def find_agent(explicit: str | None = None, fingerprint: str | None = None) -> tuple[str | None, list[str]]:
+    """The first agent socket that holds keys (or the given key, if fingerprint is set)."""
+    for sock, keys in list_agents(explicit):
+        if fingerprint is None or has_key(keys, fingerprint):
+            return sock, keys
+    return None, []
+
+
+def remote_path(path: str) -> str:
+    """Quote a path for the remote shell, keeping ~/ expansion."""
+    if path == "~":
+        return '"$HOME"'
+    if path.startswith("~/"):
+        return '"$HOME"/' + shlex.quote(path[2:])
+    return shlex.quote(path)
+
+
+class Remote:
+    """Runs commands on one server over a single multiplexed connection (ControlMaster).
+
+    Use as a context manager: the master connection is closed on exit.
+    """
+
+    def __init__(self, host: HostConfig, agent_sock: str | None = None):
+        self.host = host
+        self.agent_sock = agent_sock
+        self.env = dict(os.environ)
+        if agent_sock:
+            self.env["SSH_AUTH_SOCK"] = agent_sock
+        self.control_dir: str | None = None
+
+    def __enter__(self) -> "Remote":
+        # private (0700) directory for the control socket, removed on exit
+        self.control_dir = tempfile.mkdtemp(prefix="close1-")
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        if not self.control_dir:
+            return
+        try:
+            subprocess.run(
+                self._base() + ["-O", "exit", "--", self.host.host],
+                stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                env=self.env, timeout=30,
+            )
+        except (OSError, subprocess.SubprocessError):
+            pass
+        shutil.rmtree(self.control_dir, ignore_errors=True)
+        self.control_dir = None
+
+    def _base(self) -> list[str]:
+        cmd = ["ssh", "-o", f"ConnectTimeout={self.host.connect_timeout}"]
+        for opt in BASE_OPTIONS + self.host.ssh_options:
+            cmd += ["-o", opt]
+        if self.control_dir:
+            cmd += ["-o", "ControlMaster=auto",
+                    "-o", f"ControlPath={self.control_dir}/%C",
+                    "-o", "ControlPersist=60"]
+        if self.host.ssh_key and self.agent_sock:
+            # a specific agent was chosen for this host: override IdentityAgent from ~/.ssh/config too
+            cmd += ["-o", f"IdentityAgent={self.agent_sock}"]
+        if self.host.user:
+            cmd += ["-l", self.host.user]
+        if self.host.port:
+            cmd += ["-p", str(self.host.port)]
+        return cmd
+
+    def command(self, remote_cmd: str) -> list[str]:
+        return self._base() + ["--", self.host.host, remote_cmd]
+
+    def _run_once(self, remote_cmd: str, stdout: IO[bytes] | None) -> str:
+        r = subprocess.run(
+            self.command(remote_cmd),
+            stdin=subprocess.DEVNULL,
+            stdout=stdout if stdout is not None else subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            env=self.env,
+        )
+        if r.returncode != 0:
+            err = r.stderr.decode(errors="replace").strip()
+            raise RemoteError(remote_cmd, r.returncode, err)
+        return r.stdout.decode(errors="replace") if stdout is None else ""
+
+    def run(self, remote_cmd: str, stdout: IO[bytes] | None = None, retry: bool = False) -> str:
+        """Run a command; stdout goes to the given file or is returned as a string.
+
+        retry=True repeats the command after connection errors. Use it only for commands
+        that are safe to repeat (reads): after a dropped connection we cannot know whether
+        the command already ran.
+        """
+        attempts = 1 + (self.host.retries if retry else 0)
+        for attempt in range(1, attempts + 1):
+            try:
+                return self._run_once(remote_cmd, stdout)
+            except RemoteError as e:
+                if attempt == attempts or not is_connection_error(e):
+                    raise
+                log.warning(t("retry", name=self.host.section, n=attempt, total=attempts - 1,
+                              delay=self.host.retry_delay, error=e.stderr or e.code))
+                time.sleep(self.host.retry_delay)
+                if stdout is not None:
+                    stdout.seek(0)
+                    stdout.truncate()
+        raise AssertionError("unreachable")
+
+    def check(self) -> None:
+        self.run("true", retry=True)

close1-0.7.1.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: close1
+Version: 0.7.1
+Summary: Simple backups from servers over SSH
+Author: Yaroslav Polyakov
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/yaroslaff/close1
+Project-URL: Repository, https://github.com/yaroslaff/close1
+Project-URL: Issues, https://github.com/yaroslaff/close1/issues
+Keywords: backup,ssh,cron,pull,sqlite,mysql
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Archiving :: Backup
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=5.4
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# close1
+
+A simple tool for daily backups of files and databases over SSH.
+
+## Features
+- Pulls files and directories (.tar.gz/.zip) from the servers to your machine; nothing is installed on the servers.
+- Runs commands on the servers (for example, `mysqldump`, `.backup` in sqlite3, or stopping a web server for the duration of the backup and starting it again afterwards).
+- Good SSH integration: uses your key through the SSH agent (even if it is passphrase-protected). ControlMaster for speed and for reliability on lossy networks.
+- Tolerates missed cron runs (e.g. when the computer was off). You can run close1 from cron every hour and it still makes one backup per day.
+- Careful rotation: you set how many backups to keep (say, 7). Rotation removes the oldest ones, but it will not delete a 10-day-old backup if there were no newer ones. Even in the worst case you still have some backups.
+
+## Install
+
+```sh
+pipx install .        # or: pip install -e '.[dev]' in a venv
+```
+
+## Usage
+
+```sh
+close1 --check                 # SSH agent, keys, host reachability (copies nothing)
+close1                         # back up all hosts from the config
+close1 blog -f -v              # only blog, overwrite today's backup, verbose
+close1 log                     # show the log (-v: print its path first)
+```
+
+Config: `-c path`, otherwise the first one found of `$CLOSE1_CONFIG`, `~/.config/close1/close1.yml`, `/etc/close1.yml`
+(no merging). See `close1-example.yml` (short) and `close1-full-example.yml` (every option explained).
+Log: `~/.local/state/close1/close1.log` (root: `/var/log/close1.log`).
+
+## Config
+
+```yaml
+_default:
+  dest: ~/backups          # -> ~/backups/<host>/<YYYY-MM-DD>/
+  keep: 7
+
+blog:
+  pre:
+    - mysqldump blog | gzip > /tmp/blog-${DATE}.sql.gz
+  files:
+    - blog.sql.gz: /tmp/blog-${DATE}.sql.gz
+    - /var/www/blog/uploads
+    - /etc/nginx/sites-enabled
+  post:
+    - rm /tmp/blog-${DATE}.sql.gz
+
+"backup@bot:2222":
+  files:
+    - /opt/bot/config.yml
+  stdout:
+    packages.txt: dpkg -l
+```
+
+All options with explanations: [close1-full-example.yml](close1-full-example.yml).
+
+### SQLite
+
+Do not copy a live SQLite file (in WAL mode part of the data lives in `-wal`). Take a snapshot in `pre` and fetch it:
+
+```yaml
+pre:
+  - umask 077 && sqlite3 /opt/app/app.db ".backup /tmp/app-${DATE}.db" && gzip -f /tmp/app-${DATE}.db
+files:
+  - app.db.gz: /tmp/app-${DATE}.db.gz
+post:
+  - rm -f /tmp/app-${DATE}.db.gz
+```
+
+## Unreliable connections
+
+All commands to a host go through one SSH connection (ControlMaster), so a backup needs a single handshake.
+After a connection error (ssh exit code 255) close1 retries the connection check, file checks and downloads
+(`retries` times, `retry_delay` seconds apart). `pre`, `post` and `stdout` commands are not retried: after a dropped
+connection it is unknown whether they ran. If they fail, the backup fails and the next cron run starts it again.
+
+## cron and ssh-agent
+
+close1 authenticates through ssh-agent. If `SSH_AUTH_SOCK` is not set (as under cron), it looks for the socket in
+`/run/user/$UID/` (`openssh_agent`, `ssh-agent.socket`, `gcr/ssh`, `keyring/ssh`, `gnupg/S.gpg-agent.ssh`). ssh is always
+called with `BatchMode=yes` and `ForwardAgent=no`. While you are not logged in or the key is not loaded into the agent,
+the backup is skipped and retried on the next run.
+
+By default the first agent that holds any key is used. If you have several agents (e.g. ssh-agent and gnome-keyring)
+with different keys, set `ssh_key: SHA256:...` (globally or per host): close1 then uses the agent that holds this key
+and passes it to ssh as `IdentityAgent`. If the key is in no agent, the host is skipped. `close1 --check` lists all
+agents with their key fingerprints. The key comment (`user@host`) is not used for matching: it is arbitrary text.
+
+```cron
+17 * * * * $HOME/.local/bin/close1
+```
+
+Only errors go to stderr (and so to cron mail); everything else goes to the log.

close1-0.7.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+close1/__init__.py,sha256=jcd2L-ziBcbmeI8nWpxrl1M6YO-koFEdfcPS5Q7lgs8,78
+close1/__main__.py,sha256=xPRazbQoIrTanWfx2QEQsurf9oOglLX2l9GwF8zHDEk,54
+close1/backup.py,sha256=_RknlTMv6a5Nw7tB8hC4zFULf0LccBoekCsUAsnOx8Q,7765
+close1/cli.py,sha256=2AUFFg6LnxwAh6GGa0v6Oem3wBKdE4upiK7kjyXF-SE,6052
+close1/config.py,sha256=9M2ytwzCDJVY1aX1xwBh_IA0OrOK6-WDDL6TPXarmEc,9292
+close1/messages.py,sha256=rFFrcAxOAForhWDdQVlXvxMMCktDscapK3a6wezF7Co,1949
+close1/rotate.py,sha256=Sn1C9CW-249c9PQZjmeBeJN12Vm3bJrRAMuYMo5yYdY,652
+close1/ssh.py,sha256=o6DcZlarKn4KLLHdwaSMQKFsRpvmc2LPuDC9ZbXybao,7368
+close1-0.7.1.dist-info/licenses/LICENSE,sha256=hBsUwj1tQbFk1jd9i-yDQuIEK0aK2UARCrt52wQ-FyI,1074
+close1-0.7.1.dist-info/METADATA,sha256=O8tzBMRplZBuHTMCuvJSOahtir0pKwzyS35o6--gzCM,4834
+close1-0.7.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+close1-0.7.1.dist-info/entry_points.txt,sha256=BKgUgRg_ZvkCQokRvNhcxuzzNsQVAG9ef97w9OGcG_Y,43
+close1-0.7.1.dist-info/top_level.txt,sha256=xtwqa419VPq-4EgzrdbJ6onNeAWNsAn60Krc3knrgh4,7
+close1-0.7.1.dist-info/RECORD,,

close1-0.7.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

close1-0.7.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+close1 = close1.cli:main

close1-0.7.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaroslav Polyakov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

close1-0.7.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+close1