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

kento/inject.sh

@@ -0,0 +1,282 @@
+#!/bin/sh
+# kento guest config injection — standalone POSIX shell script.
+#
+# Usage: inject.sh <ROOTFS> <CONTAINER_DIR>
+#   $1 = ROOTFS path (where to inject guest-side files)
+#   $2 = CONTAINER_DIR (where to read kento metadata and mode from)
+#
+# Reads config from LXC/PVE config (authoritative, handles `pct set`) and
+# kento metadata files (fallback for values LXC config can't carry).
+set -eu
+
+ROOTFS="$1"
+CONTAINER_DIR="$2"
+
+# Check config mode — cloud-init seed delivery or file injection
+CONFIG_MODE="injection"
+CONFIG_MODE_FILE="$CONTAINER_DIR/kento-config-mode"
+if [ -f "$CONFIG_MODE_FILE" ]; then
+    CONFIG_MODE=$(cat "$CONFIG_MODE_FILE" | tr -d '[:space:]')
+fi
+
+# --allow-nesting: inject a networkd drop-in so the guest leaves nested
+# host-side veths unmanaged (fixes nested LXC/docker/podman bridging on
+# networkd images). Matches by Name=veth* — the interface NAME, which is set
+# at creation, so the match is race-free. (Kind=veth would also work but the
+# kind attribute can lag link-appearance, leaving a window where an image's
+# Type=ether DHCP unit claims the veth and strips its bridge master before the
+# unmanaged match applies.) veth* naturally excludes the guest's own uplink
+# eth0, so no separate exclusion is needed. Runs BEFORE the cloudinit
+# early-exit so both injection and cloudinit guests get it.
+NESTING="0"
+NESTING_FILE="$CONTAINER_DIR/kento-nesting"
+if [ -f "$NESTING_FILE" ]; then
+    NESTING=$(cat "$NESTING_FILE" | tr -d '[:space:]')
+fi
+if [ "$NESTING" = "1" ]; then
+    NEST_NET_DIR="$ROOTFS/etc/systemd/network"
+    mkdir -p "$NEST_NET_DIR"
+    {
+        echo "[Match]"
+        echo "Name=veth*"
+        echo ""
+        echo "[Link]"
+        echo "Unmanaged=yes"
+    } > "$NEST_NET_DIR/10-kento-nested-veth.network"
+fi
+
+if [ "$CONFIG_MODE" = "cloudinit" ]; then
+    # Copy pre-generated NoCloud seed files to guest rootfs
+    SEED_SRC="$CONTAINER_DIR/cloud-seed"
+    SEED_DST="$ROOTFS/var/lib/cloud/seed/nocloud"
+    if [ -d "$SEED_SRC" ]; then
+        mkdir -p "$SEED_DST"
+        cp -f "$SEED_SRC/meta-data" "$SEED_DST/" 2>/dev/null || true
+        cp -f "$SEED_SRC/user-data" "$SEED_DST/" 2>/dev/null || true
+        cp -f "$SEED_SRC/network-config" "$SEED_DST/" 2>/dev/null || true
+    fi
+    exit 0
+fi
+
+STATIC_IP=""
+STATIC_GW=""
+STATIC_DNS=""
+STATIC_SEARCH=""
+CFG_HOSTNAME=""
+CFG_TZ=""
+
+# Read kento metadata (fallback values)
+if [ -f "$CONTAINER_DIR/kento-net" ]; then
+    STATIC_DNS=$(sed -n 's/^dns=//p' "$CONTAINER_DIR/kento-net")
+    STATIC_SEARCH=$(sed -n 's/^searchdomain=//p' "$CONTAINER_DIR/kento-net")
+fi
+if [ -f "$CONTAINER_DIR/kento-tz" ]; then
+    CFG_TZ=$(cat "$CONTAINER_DIR/kento-tz")
+fi
+
+# Read LXC/PVE config (authoritative — overrides kento metadata)
+MODE=$(cat "$CONTAINER_DIR/kento-mode" 2>/dev/null || echo "lxc")
+if [ "$MODE" = "pve" ]; then
+    VMID=$(basename "$CONTAINER_DIR")
+    PVE_CONF="/etc/pve/lxc/${VMID}.conf"
+    if [ -f "$PVE_CONF" ]; then
+        # Network (from net0 line)
+        NET_LINE=$(grep '^net0:' "$PVE_CONF" || true)
+        if [ -n "$NET_LINE" ]; then
+            CFG_IP=$(echo "$NET_LINE" | tr ',' '\n' | sed -n 's/^ip=//p')
+            CFG_GW=$(echo "$NET_LINE" | tr ',' '\n' | sed -n 's/^gw=//p')
+            if [ -n "$CFG_IP" ] && [ "$CFG_IP" != "dhcp" ]; then
+                STATIC_IP="$CFG_IP"
+                STATIC_GW="${CFG_GW:-}"
+            else
+                # net0 present but no static ip (ip=dhcp or omitted) — the
+                # bridged veth is eth0 and needs a DHCP .network injected.
+                WANT_DHCP=1
+            fi
+        fi
+        # Top-level PVE directives
+        CFG_HOSTNAME=$(sed -n 's/^hostname: *//p' "$PVE_CONF")
+        CFG_NS=$(sed -n 's/^nameserver: *//p' "$PVE_CONF")
+        [ -n "$CFG_NS" ] && STATIC_DNS="$CFG_NS"
+        CFG_SD=$(sed -n 's/^searchdomain: *//p' "$PVE_CONF")
+        [ -n "$CFG_SD" ] && STATIC_SEARCH="$CFG_SD"
+        CFG_PVE_TZ=$(sed -n 's/^timezone: *//p' "$PVE_CONF")
+        [ -n "$CFG_PVE_TZ" ] && CFG_TZ="$CFG_PVE_TZ"
+
+        # Create guest-side mount point directories for mp[n] entries
+        grep '^mp[0-9]*:' "$PVE_CONF" | while IFS= read -r mp_line; do
+            MP_PATH=$(echo "$mp_line" | tr ',' '\n' | sed -n 's/^mp=//p')
+            if [ -n "$MP_PATH" ]; then
+                mkdir -p "$ROOTFS$MP_PATH"
+            fi
+        done
+    fi
+else
+    CONFIG_FILE="$CONTAINER_DIR/config"
+    if [ -f "$CONFIG_FILE" ]; then
+        CFG_IP=$(sed -n 's/^lxc\.net\.0\.ipv4\.address *= *//p' "$CONFIG_FILE")
+        CFG_GW=$(sed -n 's/^lxc\.net\.0\.ipv4\.gateway *= *//p' "$CONFIG_FILE")
+        CFG_HOSTNAME=$(sed -n 's/^lxc\.uts\.name *= *//p' "$CONFIG_FILE")
+        CFG_LINK=$(sed -n 's/^lxc\.net\.0\.link *= *//p' "$CONFIG_FILE")
+        if [ -n "$CFG_IP" ]; then
+            STATIC_IP="$CFG_IP"
+            STATIC_GW="${CFG_GW:-}"
+        elif [ "$MODE" = "lxc" ] && [ -n "$CFG_LINK" ]; then
+            # Bridge attached (lxc.net.0.link) but no static ip — the veth is
+            # eth0, so DHCP needs a matching .network. `--network none` has no
+            # link line, so this stays off there.
+            WANT_DHCP=1
+        fi
+    fi
+fi
+
+# Fall back to kento-net if LXC config has no IP
+if [ -z "$STATIC_IP" ] && [ -f "$CONTAINER_DIR/kento-net" ]; then
+    STATIC_IP=$(sed -n 's/^ip=//p' "$CONTAINER_DIR/kento-net")
+    STATIC_GW=$(sed -n 's/^gateway=//p' "$CONTAINER_DIR/kento-net")
+fi
+
+# Inject hostname
+if [ -n "${CFG_HOSTNAME:-}" ]; then
+    echo "$CFG_HOSTNAME" > "$ROOTFS/etc/hostname"
+fi
+
+# Inject network config
+if [ -n "$STATIC_IP" ]; then
+    NET_DIR="$ROOTFS/etc/systemd/network"
+    mkdir -p "$NET_DIR"
+    # VM modes use predictable naming (e.g. enp0s2), match by type.
+    # LXC/PVE modes always have eth0 (configured by LXC veth).
+    if [ "$MODE" = "vm" ] || [ "$MODE" = "pve-vm" ]; then
+        MATCH_LINE="Type=ether"
+    else
+        MATCH_LINE="Name=eth0"
+    fi
+    {
+        echo "[Match]"
+        echo "$MATCH_LINE"
+        echo ""
+        echo "[Network]"
+        echo "Address=$STATIC_IP"
+        [ -n "${STATIC_GW:-}" ] && echo "Gateway=$STATIC_GW"
+        [ -n "${STATIC_DNS:-}" ] && echo "DNS=$STATIC_DNS"
+        [ -n "${STATIC_SEARCH:-}" ] && echo "Domains=$STATIC_SEARCH"
+    # The 05- prefix sorts before any image-baked drop-in (e.g. a generic
+    # Kind=veth Unmanaged=yes unit like 10-lxc-veth-unmanaged.network). In
+    # pve-lxc the guest eth0 presents Kind=veth, so such a unit would match and
+    # win; naming kento's per-instance config 05- makes it authoritative.
+    } > "$NET_DIR/05-kento-static.network"
+elif [ "${WANT_DHCP:-0}" = 1 ]; then
+    # LXC/pve-lxc bridge + DHCP: the image may only match Name=en* (VM-oriented
+    # networkd config), but the LXC veth is eth0, so add a matching DHCP unit.
+    NET_DIR="$ROOTFS/etc/systemd/network"
+    mkdir -p "$NET_DIR"
+    {
+        echo "[Match]"
+        echo "Name=eth0"
+        echo ""
+        echo "[Network]"
+        echo "DHCP=yes"
+        [ -n "${STATIC_DNS:-}" ] && echo "DNS=$STATIC_DNS"
+        [ -n "${STATIC_SEARCH:-}" ] && echo "Domains=$STATIC_SEARCH"
+    # 05- prefix: sort before image drop-ins (e.g. a Kind=veth Unmanaged unit
+    # that would otherwise claim the pve-lxc eth0 veth) so kento's config wins.
+    } > "$NET_DIR/05-kento-dhcp.network"
+elif [ -n "${STATIC_DNS:-}" ] || [ -n "${STATIC_SEARCH:-}" ]; then
+    # No static IP but DNS/search set — use resolved drop-in
+    RESOLVED_DIR="$ROOTFS/etc/systemd/resolved.conf.d"
+    mkdir -p "$RESOLVED_DIR"
+    {
+        echo "[Resolve]"
+        [ -n "${STATIC_DNS:-}" ] && echo "DNS=$STATIC_DNS"
+        [ -n "${STATIC_SEARCH:-}" ] && echo "Domains=$STATIC_SEARCH"
+    } > "$RESOLVED_DIR/90-kento.conf"
+fi
+
+# Inject timezone
+if [ -n "${CFG_TZ:-}" ]; then
+    ln -sf "/usr/share/zoneinfo/$CFG_TZ" "$ROOTFS/etc/localtime"
+    echo "$CFG_TZ" > "$ROOTFS/etc/timezone"
+fi
+
+# Inject environment variables
+CFG_ENV=""
+if [ "$MODE" = "pve" ] && [ -f "${PVE_CONF:-}" ]; then
+    CFG_ENV=$(sed -n 's/^lxc\.environment: *//p' "$PVE_CONF")
+elif [ "$MODE" != "pve" ] && [ -f "${CONFIG_FILE:-}" ]; then
+    CFG_ENV=$(sed -n 's/^lxc\.environment *= *//p' "$CONFIG_FILE")
+fi
+# Append kento-env entries (may overlap with lxc.environment keys),
+# then deduplicate by key — config takes priority over kento-env.
+if [ -f "$CONTAINER_DIR/kento-env" ]; then
+    KENTO_ENV=$(cat "$CONTAINER_DIR/kento-env")
+    if [ -n "$CFG_ENV" ]; then
+        CFG_ENV="$CFG_ENV
+$KENTO_ENV"
+    else
+        CFG_ENV="$KENTO_ENV"
+    fi
+fi
+# Auto-inject TZ from timezone config (lowest priority — user --env TZ wins
+# because the awk dedup below keeps the first occurrence of each key).
+if [ -n "${CFG_TZ:-}" ]; then
+    if [ -n "$CFG_ENV" ]; then
+        CFG_ENV="$CFG_ENV
+TZ=$CFG_TZ"
+    else
+        CFG_ENV="TZ=$CFG_TZ"
+    fi
+fi
+if [ -n "${CFG_ENV:-}" ]; then
+    echo "$CFG_ENV" | awk -F= '!seen[$1]++' > "$ROOTFS/etc/environment"
+fi
+
+# --- SSH host key injection ---
+HOST_KEY_DIR="$CONTAINER_DIR/ssh-host-keys"
+if [ -d "$HOST_KEY_DIR" ]; then
+    mkdir -p "$ROOTFS/etc/ssh"
+    for keyfile in "$HOST_KEY_DIR"/ssh_host_*; do
+        [ -f "$keyfile" ] || continue
+        cp "$keyfile" "$ROOTFS/etc/ssh/$(basename "$keyfile")"
+    done
+    # Fix permissions
+    chmod 600 "$ROOTFS"/etc/ssh/ssh_host_*_key 2>/dev/null || true
+    chmod 644 "$ROOTFS"/etc/ssh/ssh_host_*_key.pub 2>/dev/null || true
+fi
+
+# --- SSH authorized_keys injection ---
+if [ -f "$CONTAINER_DIR/kento-authorized-keys" ]; then
+    SSH_USER="root"
+    if [ -f "$CONTAINER_DIR/kento-ssh-user" ]; then
+        SSH_USER=$(cat "$CONTAINER_DIR/kento-ssh-user" | tr -d '[:space:]')
+    fi
+    if [ "$SSH_USER" = "root" ]; then
+        SSH_HOME="/root"
+        SSH_UID=0
+        SSH_GID=0
+    else
+        # Match the first passwd field LITERALLY (exact string compare, no
+        # regex semantics). SSH_USER comes from --ssh-key-user (unvalidated);
+        # feeding it to grep as a BRE would let metacharacters (e.g. `ro.t`)
+        # match the WRONG account (`root:`) and chown keys for it.
+        SSH_PASSWD_LINE=$(awk -F: -v u="$SSH_USER" '$1==u {print; exit}' "$ROOTFS/etc/passwd" || true)
+        if [ -z "$SSH_PASSWD_LINE" ]; then
+            echo "kento-inject: warning: SSH key user '$SSH_USER' not found in rootfs /etc/passwd, skipping key injection" >&2
+            SSH_HOME=""
+        else
+            SSH_HOME=$(echo "$SSH_PASSWD_LINE" | cut -d: -f6)
+            SSH_UID=$(echo "$SSH_PASSWD_LINE" | cut -d: -f3)
+            SSH_GID=$(echo "$SSH_PASSWD_LINE" | cut -d: -f4)
+        fi
+    fi
+    if [ -n "$SSH_HOME" ]; then
+        mkdir -p "$ROOTFS$SSH_HOME/.ssh"
+        chmod 700 "$ROOTFS$SSH_HOME/.ssh"
+        cp "$CONTAINER_DIR/kento-authorized-keys" "$ROOTFS$SSH_HOME/.ssh/authorized_keys"
+        chmod 600 "$ROOTFS$SSH_HOME/.ssh/authorized_keys"
+        if [ "$SSH_USER" != "root" ]; then
+            chown "$SSH_UID:$SSH_GID" "$ROOTFS$SSH_HOME/.ssh"
+            chown "$SSH_UID:$SSH_GID" "$ROOTFS$SSH_HOME/.ssh/authorized_keys"
+        fi
+    fi
+fi

kento/layers.py

@@ -0,0 +1,81 @@
+"""Resolve OCI image layer paths via podman."""
+
+import logging
+import subprocess
+
+from kento.errors import ImageNotFoundError
+
+logger = logging.getLogger("kento")
+
+
+def _podman_cmd() -> list[str]:
+    """Return the podman command prefix."""
+    return ["podman"]
+
+
+def resolve_layers(image: str) -> str:
+    """Return colon-separated lowerdir string for an OCI image.
+
+    Queries podman for the image's GraphDriver layer paths.
+    Upper layer comes first (topmost), matching overlayfs lowerdir order.
+    """
+    podman = _podman_cmd()
+
+    result = subprocess.run(
+        [*podman, "image", "exists", image],
+        capture_output=True,
+    )
+    if result.returncode != 0:
+        raise ImageNotFoundError(
+            f"image not found in local store: {image}"
+            f" — pull it first:  kento pull {image}"
+        )
+
+    upper = subprocess.run(
+        [*podman, "image", "inspect", image,
+         "--format", "{{.GraphDriver.Data.UpperDir}}"],
+        capture_output=True, text=True, check=True,
+    ).stdout.strip()
+
+    lower = subprocess.run(
+        [*podman, "image", "inspect", image,
+         "--format", "{{.GraphDriver.Data.LowerDir}}"],
+        capture_output=True, text=True, check=True,
+    ).stdout.strip()
+
+    if lower and lower != "<no value>":
+        return f"{upper}:{lower}"
+    return upper
+
+
+def create_image_hold(image: str, name: str) -> None:
+    """Create a stopped podman container to pin the image against pruning."""
+    hold_name = f"kento-hold.{name}"
+    subprocess.run(
+        [*_podman_cmd(), "create", "--name", hold_name,
+         "--label", f"io.kento.hold-for={name}",
+         image, "/bin/true"],
+        capture_output=True,
+    )
+
+
+def ensure_image_hold(image: str, name: str) -> None:
+    """Idempotent — create the image hold only if missing (backfills pre-hold guests)."""
+    try:
+        exists = subprocess.run(
+            [*_podman_cmd(), "container", "exists", f"kento-hold.{name}"],
+            capture_output=True,
+        )
+        if exists.returncode != 0:
+            create_image_hold(image, name)
+    except Exception:
+        pass
+
+
+def remove_image_hold(name: str) -> None:
+    """Remove the podman hold container for the given kento container."""
+    hold_name = f"kento-hold.{name}"
+    subprocess.run(
+        [*_podman_cmd(), "rm", hold_name],
+        capture_output=True,
+    )

kento/list.py

@@ -0,0 +1,146 @@
+"""List kento-managed instances."""
+
+import json
+import subprocess
+from pathlib import Path
+
+from kento import LXC_BASE, VM_BASE, is_running, pve_config_exists, read_mode
+from kento.info import _get_ssh_host_key_fingerprints
+
+
+def list_containers(scope: str | None = None, show_size: bool = False,
+                    as_json: bool = False) -> str:
+    """List kento-managed instances.
+
+    Returns the rendered text (either a JSON string, the human-readable columnar
+    table, or '(no instances found)'). The caller is responsible for printing the
+    returned string; this function does not print anything.
+    """
+    instances = []
+
+    image_files = []
+    if scope in (None, "lxc"):
+        if LXC_BASE.is_dir():
+            image_files.extend(LXC_BASE.glob("*/kento-image"))
+    if scope in (None, "vm"):
+        if VM_BASE.is_dir():
+            image_files.extend(VM_BASE.glob("*/kento-image"))
+
+    for image_file in sorted(image_files, key=lambda f: f.parent.name):
+        # list is read-only introspection: a concurrent `kento destroy`
+        # (rmtree) can race between the glob above and the reads below,
+        # raising FileNotFoundError/OSError. Skip the bad entry rather than
+        # aborting the whole listing and hiding all healthy instances.
+        try:
+            container_dir = image_file.parent
+            container_id = container_dir.name
+            image = image_file.read_text().strip()
+
+            name_file = container_dir / "kento-name"
+            display_name = name_file.read_text().strip() if name_file.is_file() else container_id
+
+            mode = read_mode(container_dir)
+            # Normalize the raw mode ('pve' -> 'pve-lxc') to match info.py.
+            ctype = "pve-lxc" if mode == "pve" else mode
+            # type = LXC/VM family (same derivation as info.py).
+            family = "VM" if mode in ("vm", "pve-vm") else "LXC"
+
+            # JSON vmid mirrors info.py exactly: from the kento-vmid file only
+            # (so list --json and inspect --json agree). For plain pve-lxc the
+            # orphan check uses the dir name (which is the vmid), independent
+            # of this.
+            vmid_file = container_dir / "kento-vmid"
+            vmid = vmid_file.read_text().strip() if vmid_file.is_file() else None
+
+            # For PVE modes, surface an orphaned instance (PVE config gone,
+            # destroyed out-of-band) as "orphan" so the user can see it and
+            # clean it up with `destroy -f`.
+            if mode in ("pve", "pve-vm"):
+                check_vmid = container_dir.name if mode == "pve" else vmid
+                if check_vmid is None or not pve_config_exists(check_vmid, mode):
+                    status = "orphan"
+                else:
+                    status = "running" if is_running(container_dir, mode) else "stopped"
+            else:
+                status = "running" if is_running(container_dir, mode) else "stopped"
+
+            # Build the per-instance dict, mirroring the keys inspect --json
+            # emits so machine consumers can drop an N+1 inspect call.
+            entry: dict = {
+                "name": display_name,
+                "type": family,
+                "mode": ctype,
+                "image": image,
+                "status": status,
+            }
+            # The mac/env/vmid/fingerprint fields only surface in --json. The
+            # human table never shows them, and _get_ssh_host_key_fingerprints
+            # shells out to ssh-keygen per key — so skip all of it (especially
+            # the subprocess) on the common columnar path.
+            if as_json:
+                if vmid is not None:
+                    try:
+                        entry["vmid"] = int(vmid)
+                    except (TypeError, ValueError):
+                        entry["vmid"] = vmid
+
+                mac_file = container_dir / "kento-mac"
+                if mac_file.is_file():
+                    mac = mac_file.read_text().strip()
+                    if mac:
+                        entry["mac"] = mac
+
+                env_file = container_dir / "kento-env"
+                if env_file.is_file():
+                    env = env_file.read_text()
+                    env_lines = env.splitlines()
+                    if env_lines:
+                        entry["environment"] = env_lines
+
+                fingerprints, _ = _get_ssh_host_key_fingerprints(container_dir)
+                if fingerprints:
+                    entry["ssh_host_key_fingerprints"] = fingerprints
+
+            if show_size:
+                state_file = container_dir / "kento-state"
+                state_dir = Path(state_file.read_text().strip()) if state_file.is_file() else container_dir
+                upper_dir = state_dir / "upper"
+                if upper_dir.is_dir():
+                    du = subprocess.run(
+                        ["du", "-sh", str(upper_dir)],
+                        capture_output=True, text=True,
+                    )
+                    upper_size = du.stdout.split()[0] if du.returncode == 0 else "?"
+                else:
+                    upper_size = "0"
+                entry["upper_size"] = upper_size
+
+            instances.append(entry)
+        except OSError:
+            continue
+
+    if as_json:
+        return json.dumps(instances, indent=2)
+
+    if not instances:
+        return "(no instances found)"
+
+    if show_size:
+        rows = [(e["name"], e["mode"], e["image"], e["status"], e["upper_size"])
+                for e in instances]
+        headers = ("NAME", "TYPE", "IMAGE", "STATUS", "UPPER SIZE")
+    else:
+        rows = [(e["name"], e["mode"], e["image"], e["status"])
+                for e in instances]
+        headers = ("NAME", "TYPE", "IMAGE", "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 = ["  ".join(h.ljust(w) for h, w in zip(headers, widths)),
+             "  ".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)

kento/locking.py

@@ -0,0 +1,64 @@
+"""Cross-process lock for kento state mutations.
+
+Used by create() to serialize allocate-port / next-vmid / next-instance-name
+/ container_dir.mkdir across concurrent kento invocations. Without this, two
+concurrent `kento create` runs can allocate the same VMID, port, or
+auto-generated name.
+"""
+
+import errno
+import fcntl
+import logging
+import os
+from contextlib import contextmanager
+from pathlib import Path
+
+from kento.errors import StateError
+
+logger = logging.getLogger("kento")
+
+# Primary lock path (tmpfs-backed, cleared on reboot — fine for a lock).
+# Fallback when /run is not writable (unusual, but handles root-owned
+# read-only /run under some container setups).
+_PRIMARY_LOCK = Path("/run/kento.lock")
+_FALLBACK_LOCK = Path("/var/lib/kento/.lock")
+
+
+def _open_lock_fd() -> int:
+    """Open (creating if needed) the kento lock file and return its fd.
+
+    Tries /run/kento.lock first. Falls back to /var/lib/kento/.lock if
+    /run is not writable. The file is kept open for the duration of the
+    lock; flock is released on close.
+    """
+    for path in (_PRIMARY_LOCK, _FALLBACK_LOCK):
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            return os.open(str(path), os.O_RDWR | os.O_CREAT, 0o600)
+        except OSError:
+            continue
+    raise StateError(
+        "could not open a kento lock file at /run/kento.lock or "
+        "/var/lib/kento/.lock. Check filesystem permissions."
+    )
+
+
+@contextmanager
+def kento_lock():
+    """Acquire the kento-wide exclusive lock for the duration of a block.
+
+    Blocks until the lock is available. Use this around any sequence that
+    must be atomic across concurrent `kento` processes — notably the
+    allocate-then-write steps in create() (ports, VMIDs, auto-names, and
+    container_dir creation).
+    """
+    fd = _open_lock_fd()
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX)
+        yield
+    finally:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        except OSError:
+            pass
+        os.close(fd)

kento/logs.py

@@ -0,0 +1,48 @@
+"""Show journal logs from a kento-managed instance.
+
+Dispatch per mode:
+- lxc      -> lxc-attach -n <name> -- journalctl <args>   (inherited stdio)
+- pve      -> pct exec <vmid> -- journalctl <args>        (pve-lxc)
+- vm       -> error (use 'kento attach' for the serial console, or SSH)
+- pve-vm   -> error (same)
+
+Extra args (e.g. -f, -n, 50) are forwarded verbatim to journalctl.
+"""
+
+import logging
+import subprocess
+from pathlib import Path
+
+from kento import read_mode, require_root, resolve_any
+from kento.errors import ModeError
+
+logger = logging.getLogger("kento")
+
+
+def logs(name: str, args: list[str],
+         namespace: str | None = None) -> int:
+    """Show ``journalctl`` output for instance ``name``. Returns an exit code."""
+    require_root()
+
+    container_dir, mode = resolve_any(name, namespace)
+    if mode is None:
+        mode = read_mode(container_dir)
+
+    if mode in ("vm", "pve-vm"):
+        raise ModeError(
+            "'kento logs' is not supported for VM instances. "
+            "Use 'kento attach <name>' for the serial console, or SSH + "
+            "journalctl inside the guest."
+        )
+
+    if mode == "pve":
+        # pve-lxc: the instance directory name IS the VMID.
+        vmid = container_dir.name
+        return subprocess.run(
+            ["pct", "exec", vmid, "--", "journalctl", *args]
+        ).returncode
+
+    # plain lxc: name is the container name; inherit stdio.
+    return subprocess.run(
+        ["lxc-attach", "-n", name, "--", "journalctl", *args]
+    ).returncode

kento/lxc_hook.py

@@ -0,0 +1,61 @@
+"""Generate PVE hookscript snippets for pve-lxc containers."""
+
+import logging
+from pathlib import Path
+
+from kento.errors import StateError
+
+logger = logging.getLogger("kento")
+
+
+def generate_lxc_snippets_wrapper(hook_path: Path) -> str:
+    """Thin wrapper that maps PVE hookscript phases to kento-hook types."""
+    return f"""#!/bin/sh
+# Generated by kento. PVE strips lxc.hook.start-host, so we route
+# post-start / post-stop through this snippets wrapper to fire the
+# per-container kento-hook (the plain-LXC hook.sh).
+VMID="$1"
+PHASE="$2"
+case "$PHASE" in
+    post-start)
+        exec "{hook_path}" "$VMID" "" "start-host"
+        ;;
+    post-stop)
+        exec "{hook_path}" "$VMID" "" "post-stop"
+        ;;
+esac
+exit 0
+"""
+
+
+def write_lxc_snippets_wrapper(vmid: int, hook_path: Path, *,
+                                snippets_dir: Path | None = None,
+                                storage_name: str | None = None) -> str:
+    """Write the wrapper and return a PVE storage ref."""
+    if snippets_dir is None or storage_name is None:
+        from kento.vm_hook import find_snippets_dir
+        snippets_dir, storage_name = find_snippets_dir()
+    wrapper_name = f"kento-lxc-{vmid}.sh"
+    wrapper_path = snippets_dir / wrapper_name
+    wrapper_path.write_text(generate_lxc_snippets_wrapper(hook_path))
+    wrapper_path.chmod(0o755)
+    return f"{storage_name}:snippets/{wrapper_name}"
+
+
+def delete_lxc_snippets_wrapper(vmid: int) -> None:
+    """Delete the wrapper (no-op if missing)."""
+    try:
+        from kento.vm_hook import find_snippets_dir
+        snippets_dir, _ = find_snippets_dir()
+        wrapper = snippets_dir / f"kento-lxc-{vmid}.sh"
+        wrapper.unlink(missing_ok=True)
+    except StateError:
+        # find_snippets_dir() couldn't locate the snippets storage (no longer
+        # enabled / unlocatable). We can't compute the wrapper path, so the
+        # file (if any) is left behind. Warn rather than silently reporting a
+        # clean destroy so a leaked wrapper can be cleaned up manually.
+        logger.warning(
+            "could not locate snippets storage to remove the "
+            "kento-lxc-%s.sh hookscript wrapper; it may need manual cleanup",
+            vmid,
+        )