kento-core 1.6.0.dev1__py3-none-any.whl

kento/images.py

@@ -0,0 +1,210 @@
+"""kento images / kento prune — image listing and safe garbage collection.
+
+Each kento guest pins its OCI image against `podman prune` via a stopped
+hold container named ``kento-hold.<guestname>`` carrying the label
+``io.kento.hold-for=<guestname>`` (see layers.py). These two bare-only
+commands report on and reclaim those holds:
+
+- ``kento images`` is read-only: it lists kento-managed images, marking
+  which are in-use vs orphaned and whether a hold pins them.
+- ``kento prune`` is destructive but conservative: it removes only
+  *orphaned* hold containers (a ``kento-hold.<name>`` whose guest no
+  longer exists) and then the images those holds freed (only if no
+  surviving guest references them and no remaining hold pins them). It
+  NEVER touches a hold whose guest still exists and NEVER runs
+  ``podman prune -a``.
+"""
+
+import logging
+import subprocess
+
+from kento import LXC_BASE, VM_BASE
+from kento.layers import _podman_cmd, remove_image_hold
+
+logger = logging.getLogger("kento")
+
+# Exact podman queries used by this module:
+#   hold enumeration (name + pinned image, tab-separated, one per line):
+#       podman ps -a --filter label=io.kento.hold-for \
+#           --format {{.Label "io.kento.hold-for"}}\t{{.Image}}
+#   hold removal:       podman rm kento-hold.<name>   (via remove_image_hold)
+#   image removal:      podman image rm <image>
+# No exists check is needed: the guest-name set comes from the on-disk
+# kento-image files, and orphan-ness is computed against that set.
+
+
+def _guest_image_refs() -> dict[str, list[str]]:
+    """Map each referenced OCI image -> sorted list of guest names.
+
+    Iterates LXC_BASE + VM_BASE ``*/kento-image`` (same approach as
+    list.list_containers); guest name comes from ``kento-name`` falling
+    back to the directory name.
+    """
+    refs: dict[str, set[str]] = {}
+    for base in (LXC_BASE, VM_BASE):
+        if not base.is_dir():
+            continue
+        for image_file in base.glob("*/kento-image"):
+            container_dir = image_file.parent
+            image = image_file.read_text().strip()
+            if not image:
+                continue
+            name_file = container_dir / "kento-name"
+            name = (name_file.read_text().strip()
+                    if name_file.is_file() else container_dir.name)
+            refs.setdefault(image, set()).add(name)
+    return {img: sorted(names) for img, names in refs.items()}
+
+
+def _guest_names() -> set[str]:
+    """Set of all kento guest names across both bases (kento-name/dir)."""
+    names: set[str] = set()
+    for base in (LXC_BASE, VM_BASE):
+        if not base.is_dir():
+            continue
+        for image_file in base.glob("*/kento-image"):
+            container_dir = image_file.parent
+            name_file = container_dir / "kento-name"
+            names.add(name_file.read_text().strip()
+                      if name_file.is_file() else container_dir.name)
+    return names
+
+
+def _holds() -> list[tuple[str, str]]:
+    """Return [(held_for_name, image), ...] for every kento hold container.
+
+    Single podman query: the format string emits the hold-for label and
+    the pinned image, tab-separated.
+    """
+    result = subprocess.run(
+        [*_podman_cmd(), "ps", "-a",
+         "--filter", "label=io.kento.hold-for",
+         "--format", '{{.Label "io.kento.hold-for"}}\t{{.Image}}'],
+        capture_output=True, text=True,
+    )
+    holds: list[tuple[str, str]] = []
+    if result.returncode != 0:
+        return holds
+    for line in result.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        parts = line.split("\t")
+        held_for = parts[0].strip()
+        image = parts[1].strip() if len(parts) > 1 else ""
+        if held_for:
+            holds.append((held_for, image))
+    return holds
+
+
+def list_images(in_use_only: bool = False) -> str:
+    """List kento-managed images (read-only).
+
+    A managed image is any image referenced by a guest or pinned by a
+    hold container. Each row reports the image, the referencing guests,
+    whether a hold pins it, and an in-use/orphaned status.
+
+    Returns the rendered table as a string (no trailing newline).
+    """
+    refs = _guest_image_refs()
+    holds = _holds()
+
+    held_images: set[str] = {img for _, img in holds if img}
+
+    managed = set(refs) | held_images
+    if not managed:
+        return "No kento-managed images."
+
+    rows = []
+    for image in sorted(managed):
+        guests = refs.get(image, [])
+        status = "in-use" if guests else "orphaned"
+        if in_use_only and status != "in-use":
+            continue
+        guests_cell = ",".join(guests) if guests else "-"
+        hold_cell = "yes" if image in held_images else "no"
+        rows.append((image, guests_cell, hold_cell, status))
+
+    if not rows:
+        return "No kento-managed images."
+
+    headers = ("IMAGE", "GUESTS", "HOLD", "STATUS")
+    widths = []
+    for i, header in enumerate(headers):
+        col_max = max((len(row[i]) for row in rows), default=0)
+        widths.append(max(len(header), col_max))
+
+    lines = []
+    lines.append("  ".join(h.ljust(w) for h, w in zip(headers, widths)))
+    lines.append("  ".join("-" * w for w in widths))
+    for row in rows:
+        lines.append("  ".join(val.ljust(w) for val, w in zip(row, widths)))
+    return "\n".join(lines)
+
+
+def prune(yes: bool = False) -> str:
+    """Safe GC of orphaned kento hold containers and the images they freed.
+
+    DRY-RUN by default. Removes only holds whose guest no longer exists,
+    then images pinned solely by those orphaned holds and referenced by
+    no surviving guest. Never removes a hold whose guest exists; never
+    prunes all images.
+
+    Returns the user-facing plan/summary text as a string (no trailing newline).
+    """
+    guest_names = _guest_names()
+    refs = _guest_image_refs()  # image -> guests still present
+    holds = _holds()
+
+    orphaned = [(name, image) for name, image in holds
+                if name not in guest_names]
+    surviving = [(name, image) for name, image in holds
+                 if name in guest_names]
+
+    if not orphaned:
+        return "Nothing to prune."
+
+    # Images still pinned by a surviving (non-orphaned) hold must not be
+    # removed. Likewise, images referenced by any guest must not be removed.
+    surviving_hold_images = {img for _, img in surviving if img}
+    orphaned_images = {img for _, img in orphaned if img}
+    candidate_images = sorted(
+        img for img in orphaned_images
+        if img not in refs and img not in surviving_hold_images
+    )
+
+    if not yes:
+        lines = []
+        lines.append("Dry run — nothing removed. The following would be removed:")
+        lines.append("  Orphaned hold containers:")
+        for name, image in orphaned:
+            lines.append(f"    kento-hold.{name}  (pinned {image or '?'})")
+        if candidate_images:
+            lines.append("  Images then eligible for removal:")
+            for image in candidate_images:
+                lines.append(f"    {image}")
+        else:
+            lines.append("  Images then eligible for removal: (none)")
+        lines.append("Run 'kento prune --yes' to remove them.")
+        return "\n".join(lines)
+
+    removed_holds = 0
+    for name, _image in orphaned:
+        remove_image_hold(name)
+        removed_holds += 1
+
+    removed_images = 0
+    for image in candidate_images:
+        result = subprocess.run(
+            [*_podman_cmd(), "image", "rm", image],
+            capture_output=True, text=True,
+        )
+        if result.returncode == 0:
+            removed_images += 1
+        else:
+            # podman refuses if the image is still in use — that is the
+            # intended safety net, so we tolerate the failure and report.
+            msg = (result.stderr or result.stdout or "").strip()
+            logger.warning("skipped image %s: %s", image, msg)
+
+    return f"Removed {removed_holds} orphaned hold(s), {removed_images} image(s)."

kento/info.py

@@ -0,0 +1,274 @@
+"""Show instance details."""
+
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from kento import is_running
+
+
+def _read_meta(container_dir: Path, filename: str) -> str | None:
+    """Read a kento metadata file, return stripped content or None."""
+    f = container_dir / filename
+    return f.read_text().strip() if f.is_file() else None
+
+
+def _get_size(path: Path) -> str:
+    """Get human-readable size of a directory."""
+    result = subprocess.run(
+        ["du", "-sh", str(path)],
+        capture_output=True, text=True,
+    )
+    return result.stdout.split()[0] if result.returncode == 0 else "?"
+
+
+def _read_passthrough_args(container_dir: Path, filename: str) -> list[str]:
+    """Read a pass-through args file (kento-qemu-args or kento-pve-args).
+
+    Returns a list of non-empty lines. Absent file returns []. Written at
+    create time (v1.2.0 Phase B1); surfaced here for info output.
+    """
+    f = container_dir / filename
+    if not f.is_file():
+        return []
+    return [line for line in f.read_text().splitlines() if line]
+
+
+def _get_ssh_host_key_fingerprints(
+    container_dir: Path,
+) -> tuple[dict[str, str], bool]:
+    """Read SSH host key fingerprints from ssh-host-keys/ directory.
+
+    Returns (fingerprints_dict, has_keys) where:
+    - fingerprints_dict maps key type (e.g. "rsa") to fingerprint string
+    - has_keys is True when .pub files exist (even if ssh-keygen failed)
+
+    fingerprints_dict is empty if no host keys, no .pub files, or
+    ssh-keygen is unavailable.
+    """
+    keys_dir = container_dir / "ssh-host-keys"
+    if not keys_dir.is_dir():
+        return {}, False
+
+    pub_files = sorted(keys_dir.glob("*.pub"))
+    if not pub_files:
+        return {}, False
+
+    fingerprints: dict[str, str] = {}
+    for pub_path in pub_files:
+        # Extract key type from filename: ssh_host_rsa_key.pub -> rsa
+        stem = pub_path.stem  # e.g. ssh_host_rsa_key
+        parts = stem.split("_")
+        # Expected: ssh_host_<type>_key
+        if len(parts) >= 4 and parts[0] == "ssh" and parts[1] == "host":
+            key_type = "_".join(parts[2:-1])  # handles multi-word types
+        else:
+            key_type = stem  # fallback to full stem
+
+        try:
+            result = subprocess.run(
+                ["ssh-keygen", "-lf", str(pub_path)],
+                capture_output=True, text=True,
+            )
+        except FileNotFoundError:
+            return {}, True  # has keys but ssh-keygen not available
+
+        if result.returncode == 0 and result.stdout.strip():
+            # Output: "<bits> <fingerprint> <comment> (<type>)"
+            fields = result.stdout.strip().split()
+            if len(fields) >= 2:
+                fingerprints[key_type] = fields[1]
+
+    return fingerprints, True
+
+
+def info(name: str, *, container_dir: Path, mode: str,
+         as_json: bool = False, verbose: bool = False) -> str:
+    """Return container information as a rendered string."""
+
+    # Gather metadata
+    data = {}
+    data["name"] = _read_meta(container_dir, "kento-name") or name
+    data["image"] = _read_meta(container_dir, "kento-image") or "unknown"
+    # Normalize the raw mode ('pve' -> 'pve-lxc') so inspect --json and
+    # list --json agree on the mode string. type stays the LXC/VM family.
+    data["mode"] = "pve-lxc" if mode == "pve" else mode
+    data["type"] = "VM" if mode in ("vm", "pve-vm") else "LXC"
+    data["status"] = "running" if is_running(container_dir, mode) else "stopped"
+    data["directory"] = str(container_dir)
+
+    # State dir
+    state_text = _read_meta(container_dir, "kento-state")
+    state_dir = Path(state_text) if state_text else container_dir
+    data["state_directory"] = str(state_dir)
+
+    # Optional metadata
+    config_mode = _read_meta(container_dir, "kento-config-mode")
+    if config_mode:
+        data["config_mode"] = config_mode
+
+    vmid = _read_meta(container_dir, "kento-vmid")
+    if vmid:
+        data["vmid"] = int(vmid)
+
+    port = _read_meta(container_dir, "kento-port")
+    if port:
+        data["port"] = port
+
+    net = _read_meta(container_dir, "kento-net")
+    if net:
+        data["network"] = net
+
+    mac = _read_meta(container_dir, "kento-mac")
+    if mac:
+        data["mac"] = mac
+
+    nesting = _read_meta(container_dir, "kento-nesting")
+    if nesting is not None:
+        data["nesting"] = (nesting == "1")
+
+    tz = _read_meta(container_dir, "kento-tz")
+    if tz:
+        data["timezone"] = tz
+
+    ssh_user = _read_meta(container_dir, "kento-ssh-user") or "root"
+    data["ssh_user"] = ssh_user
+
+    env = _read_meta(container_dir, "kento-env")
+    if env:
+        data["environment"] = env.splitlines()
+
+    # Layers
+    layers_text = _read_meta(container_dir, "kento-layers")
+    if layers_text:
+        layer_paths = layers_text.split(":")
+        data["layer_count"] = len(layer_paths)
+    else:
+        layer_paths = []
+        data["layer_count"] = 0
+
+    # Created timestamp (directory mtime)
+    try:
+        mtime = os.path.getmtime(container_dir)
+        data["created"] = datetime.fromtimestamp(mtime).strftime("%Y-%m-%d %H:%M:%S")
+    except OSError:
+        data["created"] = "unknown"
+
+    # SSH host key fingerprints
+    fingerprints, has_host_keys = _get_ssh_host_key_fingerprints(container_dir)
+    data["ssh_host_key_fingerprints"] = fingerprints
+    # Track whether keys exist but ssh-keygen was missing (for human output)
+    _ssh_keygen_missing = has_host_keys and not fingerprints
+
+    # Pass-through flags (v1.2.0 Phase B4). Always emitted in JSON (empty
+    # list when absent) so machine consumers get a stable schema. Human
+    # output surfaces them only under --verbose and only when non-empty.
+    data["qemu_args"] = _read_passthrough_args(container_dir, "kento-qemu-args")
+    data["pve_args"] = _read_passthrough_args(container_dir, "kento-pve-args")
+    data["lxc_args"] = _read_passthrough_args(container_dir, "kento-lxc-args")
+
+    # Verbose additions
+    if verbose:
+        upper = state_dir / "upper"
+        if upper.is_dir():
+            data["upper_size"] = _get_size(upper)
+
+        if layer_paths:
+            data["layers"] = layer_paths
+            # Individual layer sizes, positionally aligned with layers:
+            # absent layer dirs get a None placeholder so layer_sizes[i]
+            # always corresponds to layers[i].
+            sizes = []
+            for lp in layer_paths:
+                p = Path(lp)
+                sizes.append(_get_size(p) if p.is_dir() else None)
+            data["layer_sizes"] = sizes
+
+    # Output
+    if as_json:
+        return json.dumps(data, indent=2)
+    return _format_human(data, verbose, ssh_keygen_missing=_ssh_keygen_missing)
+
+
+def _format_human(data: dict, verbose: bool, *,
+                  ssh_keygen_missing: bool = False) -> str:
+    """Return container info as a human-readable string."""
+    lines = []
+    lines.append(f"Name:       {data['name']}")
+    lines.append(f"Image:      {data['image']}")
+    lines.append(f"Mode:       {data['mode']} ({data['type']})")
+    lines.append(f"Status:     {data['status']}")
+    lines.append(f"Created:    {data['created']}")
+    lines.append(f"Directory:  {data['directory']}")
+    lines.append(f"State:      {data['state_directory']}")
+
+    if "config_mode" in data:
+        lines.append(f"Config:     {data['config_mode']}")
+
+    if "vmid" in data:
+        lines.append(f"VMID:       {data['vmid']}")
+    if "port" in data:
+        lines.append(f"Port:       {data['port']}")
+    if "network" in data:
+        lines.append(f"Network:    {data['network']}")
+    if "mac" in data:
+        lines.append(f"MAC:        {data['mac']}")
+    if "nesting" in data:
+        lines.append(f"Nesting:    {'allowed' if data['nesting'] else 'disabled'}")
+    if "timezone" in data:
+        lines.append(f"Timezone:   {data['timezone']}")
+    if data.get("ssh_user", "root") != "root":
+        lines.append(f"SSH user:   {data['ssh_user']}")
+    if "environment" in data:
+        lines.append(f"Env:        {', '.join(data['environment'])}")
+
+    lines.append(f"Layers:     {data['layer_count']}")
+
+    fp = data.get("ssh_host_key_fingerprints", {})
+    if fp:
+        lines.append("SSH host key fingerprints:")
+        # Display order: rsa, ecdsa, ed25519, then any others alphabetically
+        order = ["rsa", "ecdsa", "ed25519"]
+        ordered_keys = [k for k in order if k in fp]
+        ordered_keys += sorted(k for k in fp if k not in order)
+        for kt in ordered_keys:
+            label = kt.upper()
+            lines.append(f"  {label + ':':<10} {fp[kt]}")
+    elif ssh_keygen_missing:
+        lines.append("SSH host key fingerprints:")
+        lines.append("  ssh-keygen not found, cannot display fingerprints")
+
+    if verbose:
+        if "upper_size" in data:
+            lines.append(f"Upper size: {data['upper_size']}")
+        if "layers" in data:
+            lines.append("Layer paths:")
+            layer_sizes = data.get("layer_sizes", [])
+            for i, lp in enumerate(data["layers"]):
+                size = layer_sizes[i] if i < len(layer_sizes) else None
+                if size is None:
+                    size = "missing"
+                lines.append(f"  [{i}] {lp} ({size})")
+
+        qemu_args = data.get("qemu_args", [])
+        pve_args = data.get("pve_args", [])
+        lxc_args = data.get("lxc_args", [])
+        if qemu_args or pve_args or lxc_args:
+            lines.append("Pass-through flags:")
+            if qemu_args:
+                lines.append("  --qemu-arg:")
+                for line in qemu_args:
+                    lines.append(f"    {line}")
+            if pve_args:
+                lines.append("  --pve-arg:")
+                for line in pve_args:
+                    lines.append(f"    {line}")
+            if lxc_args:
+                lines.append("  --lxc-arg:")
+                for line in lxc_args:
+                    lines.append(f"    {line}")
+
+    return "\n".join(lines)

kento/inject.py

@@ -0,0 +1,28 @@
+"""Install the shared guest-config injection script per container.
+
+``inject.sh`` is a standalone POSIX shell script (no templating) that reads
+kento metadata + LXC/PVE config and writes guest-side config into a mounted
+rootfs. It is invoked by the LXC hook (and, in subsequent steps, by VM and
+PVE-VM code paths).
+
+Copying per container — rather than referencing the package path — keeps
+each container self-contained: it survives kento upgrades and uninstalls
+the same way ``kento-hook`` does.
+"""
+
+from pathlib import Path
+
+_SCRIPT = (Path(__file__).parent / "inject.sh").read_text()
+
+
+def generate_inject() -> str:
+    """Return the inject.sh content verbatim (no substitutions)."""
+    return _SCRIPT
+
+
+def write_inject(container_dir: Path) -> Path:
+    """Write the inject script into the container directory."""
+    inject_path = container_dir / "kento-inject.sh"
+    inject_path.write_text(generate_inject())
+    inject_path.chmod(0o755)
+    return inject_path