chroot-distro 2.3.2__tar.gz → 2.4.0__tar.gz

{chroot_distro-2.3.2 → chroot_distro-2.4.0}/.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
 
         steps:
             - name: Checkout Code
-              uses: actions/checkout@v4
+              uses: actions/checkout@v7
 
             - name: Set up Python
               uses: actions/setup-python@v6
@@ -47,7 +47,7 @@ jobs:
 
         steps:
             - name: Checkout Code
-              uses: actions/checkout@v4
+              uses: actions/checkout@v7
 
             - name: Set up Python ${{ matrix.python-version }}
               uses: actions/setup-python@v6

{chroot_distro-2.3.2 → chroot_distro-2.4.0}/.github/workflows/codeql.yml

@@ -27,7 +27,7 @@ jobs:
 
         steps:
             - name: Checkout repository
-              uses: actions/checkout@v4
+              uses: actions/checkout@v7
 
             - name: Initialize CodeQL
               uses: github/codeql-action/init@v4

{chroot_distro-2.3.2 → chroot_distro-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chroot-distro
-Version: 2.3.2
+Version: 2.4.0
 Summary: chroot-distro is a lightweight Linux container management utility built around chroot.
 Project-URL: Homepage, https://github.com/sabamdarif/chroot-distro
 Project-URL: Repository, https://github.com/sabamdarif/chroot-distro
@@ -65,7 +65,7 @@ when needed (see [First-run check](#first-run-check)).
    * [`login`](#login--start-a-shell-inside-a-container)
    * [`run`](#run--run-the-image-defined-entrypoint)
    * [`list`](#list--list-installed-containers)
-   * [`ps`](#ps--list-running-containers)
+   * [`ps`](#ps--list-active-sessions)
    * [`search`](#search--search-docker-hub)
    * [`diff`](#diff--inspect-filesystem-changes)
    * [`remove`](#remove--delete-a-container)
@@ -192,7 +192,7 @@ chroot-distro push myuser/myapp:1.0
 # Rebuild from scratch (loses all in-container data)
 chroot-distro reset ubuntu
 
-# List only the containers that are currently running
+# List active sessions (PID, container, type, user, uptime, command)
 chroot-distro ps
 
 # Search Docker Hub for an image
@@ -207,8 +207,9 @@ chroot-distro diff ubuntu
 # Unmount bindings and end active sessions
 chroot-distro unmount ubuntu
 
-# Forcibly stop a running container (SIGKILL + unmount)
+# Forcibly stop a running container (SIGKILL + unmount), by name or session PID
 chroot-distro kill ubuntu
+chroot-distro kill 12345
 
 # Permanently remove a container (unmounts active sessions first)
 chroot-distro remove ubuntu
@@ -733,20 +734,41 @@ printed.
 
 ---
 
-### `ps` — List running containers
+### `ps` — List active sessions
 
 ```
 chroot-distro ps [OPTIONS]
 ```
 
-List only containers that are currently **running** — those with a live
-process inside their chroot or an active namespace holder. Columns match
-`list` (rootfs size, image source, status). Does not require root.
+List every active container session — one row per live `login` or `run`.
+Each session is tracked by a per-PID JSON file under
+`$RUNTIME_DIR/sessions/` with flock-based liveness detection (immune to
+PID recycling and crash-safe). Does not require root.
+
+Output columns:
+
+| Column | Description |
+|---|---|
+| `PID` | Host PID of the session's chroot process. |
+| `CONTAINER` | Container name. |
+| `TYPE` | `login` or `run` (recorded at session start). |
+| `USER` | User the session runs as. |
+| `UPTIME` | Elapsed time since session start (e.g. `3m12s`, `1h04m`). |
+| `COMMAND` | Inner command line (shell-quoted, truncated to terminal width). |
+
+Example output:
+
+```
+PID     CONTAINER  TYPE   USER  UPTIME  COMMAND
+12345   ubuntu     login  root  3m12s   /bin/bash -l
+12388   debian     run*    root  0m44s   nginx -g 'daemon off;'
+
+* detached session
+```
 
 | Option | Description |
 |---|---|
-| `-a`, `--all` | Show all installed containers, not just running ones. |
-| `-q`, `--quiet` | Print only container names, one per line. |
+| `-q`, `--quiet` | Print only PIDs, one per line (for scripting). |
 
 ---
 
@@ -839,14 +861,12 @@ fallback.
 ### `kill` — Forcibly stop a running container
 
 ```
-chroot-distro kill CONTAINER
-Aliases: k, stop
+chroot-distro kill (CONTAINER | PID)
 ```
 
-Forcibly stop a running container: all processes inside its chroot are
-sent `SIGTERM` and then `SIGKILL` after a short grace period, the bind
-mounts are unmounted, and the namespace holder (if any) is released. This
-is the abrupt counterpart to `unmount` (equivalent to `docker kill`).
+Forcibly stop a running container. The argument may be a container name or a session PID shown in `chroot-distro ps`. When a session PID is provided, the entire container that the session belongs to is stopped. Only PIDs from active chroot-distro sessions are accepted; random host PIDs are rejected.
+
+All processes inside the container's chroot are sent `SIGTERM` and then `SIGKILL` after a short grace period, the bind mounts are unmounted, and the namespace holder (if any) is released. This is the abrupt counterpart to `unmount` (equivalent to `docker kill`).
 
 ---
 
@@ -1114,7 +1134,9 @@ Unlike `proot`, which rewrites paths via `ptrace`, Chroot-Distro uses
 real kernel features:
 
 - **Bind mounts** (`mount --bind`) for host directories inside the guest.
-- **Session tracking** under `$RUNTIME_DIR/data/<name>/sessions`.
+- **Session tracking** under `$RUNTIME_DIR/data/<name>/sessions` (counter)
+  and `$RUNTIME_DIR/sessions/<pid>.json` (per-session registry for `ps`,
+  with `flock`-based liveness detection).
 - **Automatic mount/unmount**: the first session mounts; the last session
   exiting unmounts everything.
 - **Lazy unmount fallback** (`umount -l`) when a target is busy.

{chroot_distro-2.3.2 → chroot_distro-2.4.0}/README.md

@@ -36,7 +36,7 @@ when needed (see [First-run check](#first-run-check)).
    * [`login`](#login--start-a-shell-inside-a-container)
    * [`run`](#run--run-the-image-defined-entrypoint)
    * [`list`](#list--list-installed-containers)
-   * [`ps`](#ps--list-running-containers)
+   * [`ps`](#ps--list-active-sessions)
    * [`search`](#search--search-docker-hub)
    * [`diff`](#diff--inspect-filesystem-changes)
    * [`remove`](#remove--delete-a-container)
@@ -163,7 +163,7 @@ chroot-distro push myuser/myapp:1.0
 # Rebuild from scratch (loses all in-container data)
 chroot-distro reset ubuntu
 
-# List only the containers that are currently running
+# List active sessions (PID, container, type, user, uptime, command)
 chroot-distro ps
 
 # Search Docker Hub for an image
@@ -178,8 +178,9 @@ chroot-distro diff ubuntu
 # Unmount bindings and end active sessions
 chroot-distro unmount ubuntu
 
-# Forcibly stop a running container (SIGKILL + unmount)
+# Forcibly stop a running container (SIGKILL + unmount), by name or session PID
 chroot-distro kill ubuntu
+chroot-distro kill 12345
 
 # Permanently remove a container (unmounts active sessions first)
 chroot-distro remove ubuntu
@@ -704,20 +705,41 @@ printed.
 
 ---
 
-### `ps` — List running containers
+### `ps` — List active sessions
 
 ```
 chroot-distro ps [OPTIONS]
 ```
 
-List only containers that are currently **running** — those with a live
-process inside their chroot or an active namespace holder. Columns match
-`list` (rootfs size, image source, status). Does not require root.
+List every active container session — one row per live `login` or `run`.
+Each session is tracked by a per-PID JSON file under
+`$RUNTIME_DIR/sessions/` with flock-based liveness detection (immune to
+PID recycling and crash-safe). Does not require root.
+
+Output columns:
+
+| Column | Description |
+|---|---|
+| `PID` | Host PID of the session's chroot process. |
+| `CONTAINER` | Container name. |
+| `TYPE` | `login` or `run` (recorded at session start). |
+| `USER` | User the session runs as. |
+| `UPTIME` | Elapsed time since session start (e.g. `3m12s`, `1h04m`). |
+| `COMMAND` | Inner command line (shell-quoted, truncated to terminal width). |
+
+Example output:
+
+```
+PID     CONTAINER  TYPE   USER  UPTIME  COMMAND
+12345   ubuntu     login  root  3m12s   /bin/bash -l
+12388   debian     run*    root  0m44s   nginx -g 'daemon off;'
+
+* detached session
+```
 
 | Option | Description |
 |---|---|
-| `-a`, `--all` | Show all installed containers, not just running ones. |
-| `-q`, `--quiet` | Print only container names, one per line. |
+| `-q`, `--quiet` | Print only PIDs, one per line (for scripting). |
 
 ---
 
@@ -810,14 +832,12 @@ fallback.
 ### `kill` — Forcibly stop a running container
 
 ```
-chroot-distro kill CONTAINER
-Aliases: k, stop
+chroot-distro kill (CONTAINER | PID)
 ```
 
-Forcibly stop a running container: all processes inside its chroot are
-sent `SIGTERM` and then `SIGKILL` after a short grace period, the bind
-mounts are unmounted, and the namespace holder (if any) is released. This
-is the abrupt counterpart to `unmount` (equivalent to `docker kill`).
+Forcibly stop a running container. The argument may be a container name or a session PID shown in `chroot-distro ps`. When a session PID is provided, the entire container that the session belongs to is stopped. Only PIDs from active chroot-distro sessions are accepted; random host PIDs are rejected.
+
+All processes inside the container's chroot are sent `SIGTERM` and then `SIGKILL` after a short grace period, the bind mounts are unmounted, and the namespace holder (if any) is released. This is the abrupt counterpart to `unmount` (equivalent to `docker kill`).
 
 ---
 
@@ -1085,7 +1105,9 @@ Unlike `proot`, which rewrites paths via `ptrace`, Chroot-Distro uses
 real kernel features:
 
 - **Bind mounts** (`mount --bind`) for host directories inside the guest.
-- **Session tracking** under `$RUNTIME_DIR/data/<name>/sessions`.
+- **Session tracking** under `$RUNTIME_DIR/data/<name>/sessions` (counter)
+  and `$RUNTIME_DIR/sessions/<pid>.json` (per-session registry for `ps`,
+  with `flock`-based liveness detection).
 - **Automatic mount/unmount**: the first session mounts; the last session
   exiting unmounts everything.
 - **Lazy unmount fallback** (`umount -l`) when a target is busy.

{chroot_distro-2.3.2 → chroot_distro-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "chroot-distro"
-version = "2.3.2"
+version = "2.4.0"
 description = "chroot-distro is a lightweight Linux container management utility built around chroot."
 readme = "README.md"
 requires-python = ">=3.10"

{chroot_distro-2.3.2 → chroot_distro-2.4.0}/src/chroot_distro/commands/help/pages.py

@@ -9,11 +9,19 @@ from chroot_distro.constants import (
 
 _ISOLATED_OPT = (
     "--isolated",
-    "Enable Isolated Mode: fewer host bind mounts plus Linux namespace isolation "
-    "(mount, PID, UTS, IPC via unshare/nsenter). On Termux, skip Android system, "
-    "storage, and $PREFIX bindings unless requested with --shared-* or --bind. "
-    "On Linux, skip default /tmp and display sharing unless --shared-tmp or "
-    "--shared-display. Not a full container runtime (no network namespace).",
+    "Maximum isolation: bind NOTHING from the host plus Linux namespace "
+    "isolation (mount, PID, UTS, IPC via unshare/nsenter). The host /dev, "
+    "/sys and /proc are NOT bound; the container gets a fresh procfs, a "
+    "read-only sysfs and a fresh tmpfs /dev (null, zero, tty, random, "
+    "urandom, full) instead. The namespace holder (PID 1) is itself chrooted "
+    "into the rootfs and the procfs is mounted with hidepid=2, so there is no "
+    "host path to escape through (e.g. 'chroot /proc/1/root' no longer reaches "
+    "the host). Requires kernel "
+    "namespace support; aborts if unavailable. Sharing flags (--shared-home, "
+    "--shared-tmp, --shared-display, --bind) are ignored and a warning is "
+    "printed, since they would expose a host path. Use CD_USE_NS=1 instead if "
+    "you want namespace isolation but keep the default mounts. Not a full "
+    "container runtime (no network namespace).",
 )
 _MINIMAL_OPT = (
     "--minimal",
@@ -570,10 +578,18 @@ HELP_PAGES: dict[str, dict[str, typing.Any]] = {
             ),
             ("-w, --work-dir [PATH]", "Set the initial working directory."),
             ("-e, --env VAR=VALUE", "Set an environment variable. Can be specified multiple times."),
+            (
+                "-d, --detach",
+                "Run the command in the background and return immediately. "
+                "Output is written to a per-container log file (its path is "
+                "printed) and the container stays mounted. Stop the detached "
+                f"command with '{PROGRAM_NAME} kill CONTAINER'.",
+            ),
             ("--get-chroot-cmd", "Print the fully assembled chroot command line and exit without running it."),
         ],
         "examples": [
             f"{PROGRAM_NAME} run nextcloud",
+            f"{PROGRAM_NAME} run --detach nextcloud",
             f"{PROGRAM_NAME} run ubuntu --isolated -- /bin/echo hi",
         ],
         "footer": [
@@ -591,37 +607,39 @@ HELP_PAGES: dict[str, dict[str, typing.Any]] = {
         ],
     },
     "kill": {
-        "usage": "kill CONTAINER",
+        "usage": "kill (CONTAINER | PID)",
         "aliases": ("k", "stop"),
         "summary": (
-            "Forcibly stop a running container. All processes inside the "
-            "container's chroot are sent SIGTERM and then SIGKILL after a "
-            "short grace period, the filesystem bindings are unmounted, and "
-            "the namespace holder (if any) is released. This is the abrupt "
-            "counterpart to 'unmount'."
+            "Forcibly stop a running container. The argument may be a container "
+            "name or a session PID shown by 'ps'. When a PID is given, the "
+            "owning container is resolved from the session registry; arbitrary "
+            "host PIDs are rejected. All processes inside the container's chroot "
+            "are sent SIGTERM and then SIGKILL after a short grace period, the "
+            "filesystem bindings are unmounted, and the namespace holder (if any) "
+            "is released. This is the abrupt counterpart to 'unmount'."
         ),
         "options": [
             ("-h, --help", "Show this help."),
         ],
         "examples": [
             f"{PROGRAM_NAME} kill ubuntu",
+            f"{PROGRAM_NAME} kill 111579",
         ],
     },
     "ps": {
         "usage": "ps [OPTIONS]",
         "summary": (
-            "List running containers: those with a live process inside their "
-            "chroot or an active namespace holder. Shows rootfs size, image "
-            "source, and status, like 'list'."
+            "List every active container session (one row per live "
+            "login or run). Shows PID, container name, session type "
+            "(login or run), user, uptime, and command."
         ),
         "options": [
             ("-h, --help", "Show this help."),
-            ("-a, --all", "Show all installed containers, not just running ones."),
-            ("-q, --quiet", "Print only container names, one per line."),
+            ("-q, --quiet", "Print only PIDs, one per line (for scripting)."),
         ],
         "examples": [
             f"{PROGRAM_NAME} ps",
-            f"{PROGRAM_NAME} ps --all",
+            f"{PROGRAM_NAME} ps -q",
         ],
     },
     "diff": {
@@ -753,7 +771,7 @@ TOP_COMMANDS = [
     ("sync", "Sync files from/to container."),
     ("build", "Build an OCI image from a Dockerfile."),
     ("push", "Push a locally built image to a registry."),
-    ("ps", "List running containers."),
+    ("ps", "List active container sessions."),
     ("kill", "Forcibly stop a running container."),
     ("diff", "Inspect filesystem changes in a container."),
     ("search", "Search Docker Hub for images."),

{chroot_distro-2.3.2 → chroot_distro-2.4.0}/src/chroot_distro/commands/info.py

@@ -6,6 +6,18 @@ import subprocess
 from dataclasses import dataclass, field
 
 from chroot_distro.arch import detect_installed_arch, get_device_cpu_arch, supports_32bit
+from chroot_distro.commands.kernel_config import (
+    CONFIG_BUILTIN,
+    CONFIG_MODULE,
+    CONFIG_UNKNOWN,
+    KERNEL_FLAG_GROUPS,
+    PROBE_ABSENT,
+    PROBE_PRESENT,
+    find_kernel_config,
+    lookup_flag,
+    parse_kernel_config,
+    probe_flag_runtime,
+)
 from chroot_distro.commands.list_cmd import (
     _ensure_manifest_readable,
     _iter_container_names,
@@ -525,22 +537,95 @@ def _render_capabilities(caps: list[_Capability]) -> None:
         )
 
 
+def _flag_status(flag, parsed: dict | None) -> tuple[str, str, str, bool]:
+    """Resolve one kernel flag to (glyph, color, state_text, counts_as_missing).
+
+    Uses the static kernel config when available; otherwise falls back to a
+    live runtime probe (so Android, where /proc/config.gz is root-only and
+    `info` runs rootless, still gets a meaningful answer). *counts_as_missing*
+    is True only when the option is both required and confirmed absent, so the
+    summary line never flags a merely-unknown option as blocking.
+    """
+    if parsed is not None:
+        status = lookup_flag(parsed, flag.name)
+        if status in (CONFIG_BUILTIN, CONFIG_MODULE):
+            state = "enabled" if status == CONFIG_BUILTIN else "enabled (module)"
+            return _OK, "GREEN", state, False
+        if status == CONFIG_UNKNOWN:
+            return "\u2022", "CYAN", "unknown", False
+        # Confirmed missing in a readable config.
+        if flag.required:
+            return _BAD, "RED", "missing (required)", True
+        return _WARN, "YELLOW", "missing (optional)", False
+
+    # No static config: probe the live kernel.
+    probe = probe_flag_runtime(flag.name)
+    if probe == PROBE_PRESENT:
+        return _OK, "GREEN", "available (runtime)", False
+    if probe == PROBE_ABSENT:
+        if flag.required:
+            return _BAD, "RED", "unavailable (required)", True
+        return _WARN, "YELLOW", "unavailable (optional)", False
+    return "\u2022", "CYAN", "unknown", False
+
+
+def _render_kernel_config() -> None:
+    """Show which CONFIG_* options chroot-distro relies on are enabled.
+
+    Prefers the static kernel build config (``/proc/config.gz`` and friends).
+    When that cannot be read (commonly on Android, where /proc/config.gz is
+    root-only and `info` runs rootless), it falls back to probing the running
+    kernel directly (namespace files, /proc/filesystems, /sys/fs/cgroup) so
+    the report stays useful instead of giving up.
+    """
+    _render_section("KERNEL CONFIG")
+    path, text = find_kernel_config()
+    parsed = parse_kernel_config(text) if text is not None else None
+
+    if parsed is not None:
+        msg(f"  {C['CYAN']}Read from {path}{C['RST']}")
+    else:
+        msg(
+            f"  {C['CYAN']}Kernel config not readable; probing the running "
+            f"kernel instead. For a definitive report run "
+            f"'CONFIG=/path/to/.config {PROGRAM_NAME} info' or as root.{C['RST']}"
+        )
+
+    missing_required: list[str] = []
+    for group in KERNEL_FLAG_GROUPS:
+        msg()
+        msg(f"  {C['WHITE']}{group.title}{C['RST']}")
+        label_w = max(len("CONFIG_" + flag.name) for flag in group.flags) + 1
+        for flag in group.flags:
+            glyph, color, state, counts_missing = _flag_status(flag, parsed)
+            if counts_missing:
+                missing_required.append("CONFIG_" + flag.name)
+            label = "CONFIG_" + flag.name
+            msg(
+                f"    {C[color]}{glyph}{C['RST']} "
+                f"{C['CYAN']}{label + ':':<{label_w}}{C['RST']} "
+                f"{C['WHITE']}{state}{C['RST']} "
+                f"{C['CYAN']}({flag.purpose}){C['RST']}"
+            )
+
+    msg()
+    if missing_required:
+        msg(
+            f"  {C['RED']}{_BAD}{C['RST']} "
+            f"{C['WHITE']}Namespace isolation (--isolated, CD_USE_NS=1) cannot "
+            f"work fully without: {', '.join(missing_required)}.{C['RST']}"
+        )
+    else:
+        msg(
+            f"  {C['GREEN']}{_OK}{C['RST']} "
+            f"{C['WHITE']}All kernel options required for namespace isolation "
+            f"are present.{C['RST']}"
+        )
+
+
 def _running_summary(images: list[_ImageInfo]) -> int:
     """Return the number of containers with live processes or a namespace holder."""
-    if not images:
-        return 0
-    try:
-        from chroot_distro.commands.ps import _is_running
-    except ImportError:
-        return 0
-    count = 0
-    for img in images:
-        try:
-            if _is_running(img.name):
-                count += 1
-        except OSError:
-            continue
-    return count
+    return sum(1 for img in images if img.status != "idle")
 
 
 def _render_analysis(images: list[_ImageInfo]) -> None:
@@ -575,6 +660,7 @@ def command_info(args) -> None:
     _render_basic()
     _render_host(host, host_arch)
     _render_capabilities(capabilities)
+    _render_kernel_config()
     _render_images(images)
     if images:
         msg()