chroot-distro 1.5.6__py3-none-any.whl

chroot_distro/__init__.py

@@ -0,0 +1,6 @@
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("chroot-distro")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "rolling"

chroot_distro/arch.py

@@ -0,0 +1,135 @@
+import ctypes
+import os
+import struct
+
+from chroot_distro.constants import TERMUX_PREFIX
+
+# ---------------------------------------------------------------------------
+# Host/Guest CPU architecture detection
+# ---------------------------------------------------------------------------
+
+
+def get_device_cpu_arch() -> str:
+    """Return the host CPU arch in chroot-distro's naming scheme.
+
+    armv7l / armv8l are collapsed to "arm"; everything else is the
+    raw `uname -m` value.
+    """
+    machine = os.uname().machine
+    if machine in ("armv7l", "armv8l"):
+        return "arm"
+    return machine
+
+
+def supports_32bit() -> bool:
+    """Return True if the host CPU supports 32-bit userspace execution."""
+    machine = os.uname().machine
+
+    if machine in ("x86_64", "amd64"):
+        return True
+
+    if machine in ("aarch64", "arm64"):
+        per_linux32 = 0x0008
+        try:
+            libc = ctypes.CDLL(None)
+            prev = libc.personality(per_linux32)
+
+            if prev == -1:
+                return False
+            libc.personality(prev)  # restore
+            return True
+        except Exception:
+            return False
+
+    return True
+
+
+_ELF_MACHINE_MAP = {
+    3: "i686",  # EM_386
+    40: "arm",  # EM_ARM
+    62: "x86_64",  # EM_X86_64
+    183: "aarch64",  # EM_AARCH64
+    243: "riscv64",  # EM_RISCV
+}
+
+
+def _elf_arch(path: str) -> str:
+    """Return the arch name for an ELF binary, or '' on failure."""
+    try:
+        with open(path, "rb") as fh:
+            ident = fh.read(20)
+        if len(ident) < 20 or ident[:4] != b"\x7fELF":
+            return ""
+        fmt = "<H" if ident[5] == 1 else ">H"  # EI_DATA: 1=LE, 2=BE
+        e_machine = struct.unpack_from(fmt, ident, 18)[0]
+        return _ELF_MACHINE_MAP.get(e_machine, "")
+    except OSError:
+        return ""
+
+
+def detect_installed_arch(container_name_or_rootfs: str) -> str:
+    """Detect CPU architecture of an installed container by reading ELF headers.
+
+    Accepts either a plain container name (resolved via paths.container_rootfs)
+    or a full path to the rootfs directory.
+    """
+    if os.sep in container_name_or_rootfs or container_name_or_rootfs.startswith("/"):
+        root = container_name_or_rootfs
+    else:
+        from chroot_distro.paths import container_rootfs
+
+        root = container_rootfs(container_name_or_rootfs)
+
+    candidates = [
+        "/usr/bin/bash",
+        "/usr/bin/sh",
+        "/usr/bin/su",
+        "/usr/bin/busybox",
+        f"{TERMUX_PREFIX}/bin/bash",
+        "/bin/bash",
+        "/bin/sh",
+        "/bin/su",
+        "/bin/busybox",
+    ]
+    for rel in candidates:
+        arch = _elf_arch(root + rel)
+        if arch:
+            return arch
+    return "unknown"
+
+
+_KNOWN_ARCHS = {"aarch64", "arm", "i686", "riscv64", "x86_64"}
+
+# Docker platform strings and alternative names -> chroot-distro arch.
+_DOCKER_TO_PROOT = {
+    "arm64": "aarch64",
+    "arm/v7": "arm",
+    "arm": "arm",
+    "386": "i686",
+    "amd64": "x86_64",
+    "riscv64": "riscv64",
+}
+
+
+def normalize_arch(arch: str) -> str | None:
+    """Return a canonical chroot-distro arch name, or None if unrecognised.
+
+    Accepts native names (aarch64, x86_64 ...), bare Docker names
+    (arm64, amd64 ...), and linux/-prefixed Docker platform strings.
+    """
+    s = arch.strip()
+    if s.startswith("linux/"):
+        s = s[6:]
+    if s in _KNOWN_ARCHS:
+        return s
+    return _DOCKER_TO_PROOT.get(s)
+
+
+# Machine string reported by `uname -m` for each arch.
+ARCH_UNAME_M = {
+    "aarch64": "aarch64",
+    "arm": "armv7l",
+    "i686": "i686",
+    "x86_64": "x86_64",
+    "riscv64": "riscv64",
+}

chroot_distro/atomic.py

@@ -0,0 +1,23 @@
+import contextlib
+import os
+import tempfile
+
+
+@contextlib.contextmanager
+def atomic_replace(path: str, *, suffix: str = ".tmp"):
+    """Yield a tmp path next to *path*; rename on success, remove on error."""
+    dest_dir = os.path.dirname(path) or "."
+    os.makedirs(dest_dir, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(
+        prefix=os.path.basename(path) + ".",
+        suffix=suffix,
+        dir=dest_dir,
+    )
+    os.close(fd)
+    try:
+        yield tmp
+        os.replace(tmp, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.remove(tmp)
+        raise

chroot_distro/cli.py

@@ -0,0 +1,235 @@
+import os
+import signal
+import sys
+
+from chroot_distro.commands.backup import command_backup
+from chroot_distro.commands.build import command_build
+from chroot_distro.commands.clear_cache import command_clear_cache
+from chroot_distro.commands.copy import command_copy
+from chroot_distro.commands.help import HELP_COMMANDS, command_help
+from chroot_distro.commands.install import command_install
+from chroot_distro.commands.list_cmd import command_list
+from chroot_distro.commands.login import command_login
+from chroot_distro.commands.push import command_push
+from chroot_distro.commands.remove import command_remove
+from chroot_distro.commands.rename import command_rename
+from chroot_distro.commands.reset import command_reset
+from chroot_distro.commands.restore import command_restore
+from chroot_distro.commands.run import command_run
+from chroot_distro.commands.sync import command_sync
+from chroot_distro.commands.unmount import command_unmount
+from chroot_distro.constants import IS_TERMUX, PROGRAM_NAME
+from chroot_distro.exceptions import ChrootDistroError, RootRequiredError
+from chroot_distro.message import crit_error, msg, set_quiet
+from chroot_distro.parser import (
+    ALIAS_TO_CANONICAL,
+    REQUIRED_ARGS,
+    build_parser,
+)
+
+
+def command_stub(args) -> None:
+    raise NotImplementedError(f"Command '{args.command}' is not yet implemented.")
+
+
+_COMMAND_HANDLERS = {
+    "install": command_install,
+    "remove": command_remove,
+    "rename": command_rename,
+    "reset": command_reset,
+    "login": command_login,
+    "list": command_list,
+    "backup": command_backup,
+    "restore": command_restore,
+    "clear-cache": command_clear_cache,
+    "copy": command_copy,
+    "sync": command_sync,
+    "run": command_run,
+    "unmount": command_unmount,
+    "build": command_build,
+    "push": command_push,
+    "help": command_help,
+}
+
+
+def _sigquit_to_keyboard_interrupt(_signum, _frame):
+    raise KeyboardInterrupt()
+
+
+def _ensure_root_user(no_elevate: bool = False, use_sudo: bool = False) -> None:
+    """Ensure that we are running as root, elevating if necessary/possible.
+
+    Unlike proot-distro (which is rootless), chroot-distro uses the host's
+    native chroot and mount mechanisms, requiring root privileges.
+    """
+    if os.getuid() == 0:
+        return
+
+    if no_elevate:
+        raise RootRequiredError(f"{PROGRAM_NAME} requires root privileges. Please run with sudo or as root.")
+
+    from chroot_distro.elevate import elevate_or_die
+
+    elevate_or_die(use_sudo=use_sudo)
+
+
+def _dispatch_help(raw_args) -> bool:
+    """Render per-command help when -h/--help/--usage is given."""
+    if len(raw_args) < 2 or raw_args[1] not in ("-h", "--help", "--usage"):
+        return False
+    cmd = ALIAS_TO_CANONICAL.get(raw_args[0], raw_args[0])
+    if cmd in HELP_COMMANDS:
+        HELP_COMMANDS[cmd]()
+        return True
+    return False
+
+
+def _reject_unknown_command(raw_args) -> None:
+    """Exit with help text when the first arg names no known command."""
+    if not raw_args:
+        return
+    first = raw_args[0]
+    if not first.startswith("-") and first not in _COMMAND_HANDLERS and first not in ALIAS_TO_CANONICAL:
+        msg()
+        crit_error(f"unknown command '{first}'.")
+        command_help()
+        msg()
+        sys.exit(1)
+
+
+def _split_separator(canonical, raw_args, args):
+    """Set args.login_cmd / args.run_args from tokens after a literal '--'."""
+    if canonical == "login":
+        if "--" in raw_args:
+            sep_idx = raw_args.index("--")
+            args.login_cmd = raw_args[sep_idx + 1 :]
+        else:
+            args.login_cmd = []
+    elif canonical == "run":
+        if "--" in raw_args:
+            sep_idx = raw_args.index("--")
+            args.run_args = raw_args[sep_idx + 1 :]
+        else:
+            args.run_args = []
+
+
+def main() -> None:
+    """CLI entry point.
+
+    Validates the runtime environment, parses arguments, and dispatches
+    to the chosen command's handler.
+    """
+    signal.signal(signal.SIGQUIT, _sigquit_to_keyboard_interrupt)
+
+    if len(sys.argv) >= 2:
+        ALIAS_TO_CANONICAL.get(sys.argv[1], sys.argv[1])
+
+    if len(sys.argv) < 2 or sys.argv[1] in ("-h", "--help", "help", "hel", "he", "h"):
+        command_help()
+        sys.exit(0)
+
+    raw_args = sys.argv[1:]
+    if _dispatch_help(raw_args):
+        sys.exit(0)
+
+    _reject_unknown_command(raw_args)
+
+    parser = build_parser()
+    args, unknown = parser.parse_known_args(raw_args)
+
+    command = args.command
+    if command is None:
+        msg()
+        crit_error(f"unknown command '{raw_args[0]}'.")
+        command_help()
+        msg()
+        sys.exit(1)
+
+    canonical = ALIAS_TO_CANONICAL.get(command, command)
+
+    if getattr(args, "help", False):
+        if canonical in HELP_COMMANDS:
+            HELP_COMMANDS[canonical]()
+        else:
+            command_help()
+        sys.exit(0)
+
+    check_unknown = unknown
+    if canonical in ("login", "run") and "--" in raw_args:
+        sep_idx = raw_args.index("--")
+        _, check_unknown = parser.parse_known_args(raw_args[:sep_idx])
+    if check_unknown:
+        bad = check_unknown[0]
+        kind = "unrecognized option" if bad.startswith("-") else "unexpected argument"
+        msg()
+        crit_error(f"{kind}: '{bad}'.")
+        if canonical in HELP_COMMANDS:
+            HELP_COMMANDS[canonical]()
+        msg()
+        sys.exit(1)
+
+    for arg_name, error_msg in REQUIRED_ARGS.get(canonical, []):
+        if getattr(args, arg_name, None) is None:
+            msg()
+            crit_error(error_msg)
+            if canonical in HELP_COMMANDS:
+                HELP_COMMANDS[canonical]()
+            sys.exit(1)
+
+    _split_separator(canonical, raw_args, args)
+
+    if canonical != "list" and getattr(args, "quiet", False):
+        set_quiet(True)
+
+    # Root check requirement:
+    # - In normal Linux: all commands require root except "help"
+    # - In Termux: all commands require root except "list" and "help"
+    requires_root = False
+    if IS_TERMUX:
+        if canonical not in ("list", "help"):
+            requires_root = True
+    elif canonical != "help":
+        requires_root = True
+
+    if requires_root:
+        no_elevate = getattr(args, "no_elevate", False) or os.environ.get("CHROOT_DISTRO_NO_ELEVATE") == "1"
+        use_sudo = getattr(args, "use_sudo", False) or os.environ.get("CHROOT_DISTRO_USE_SUDO") == "1"
+        try:
+            _ensure_root_user(no_elevate=no_elevate, use_sudo=use_sudo)
+        except RootRequiredError as e:
+            msg()
+            crit_error(str(e))
+            msg()
+            sys.exit(1)
+
+    handler = _COMMAND_HANDLERS.get(canonical)
+    if handler is None:
+        crit_error(f"unknown command '{command}'.")
+        sys.exit(1)
+
+    try:
+        handler(args)
+    except ChrootDistroError as e:
+        msg()
+        crit_error(str(e))
+        msg()
+        sys.exit(1)
+    except KeyboardInterrupt:
+        msg()
+        crit_error("Aborted by user.")
+        msg()
+        sys.exit(1)
+    except NotImplementedError as e:
+        msg()
+        crit_error(str(e))
+        msg()
+        sys.exit(1)
+    except Exception as e:
+        msg()
+        crit_error(f"unexpected error: {e}")
+        msg()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

chroot_distro/commands/backup.py

@@ -0,0 +1,292 @@
+import contextlib
+import os
+import stat
+import sys
+import tarfile
+
+import chroot_distro.helpers.mount_manager as mount_manager
+import chroot_distro.helpers.session as session
+from chroot_distro.locking import ContainerLock
+from chroot_distro.message import crit_error, log_error, log_info
+from chroot_distro.names import require_valid_name
+from chroot_distro.paths import container_manifest, container_rootfs
+from chroot_distro.progress import (
+    REDRAW_THRESHOLD_BYTES,
+    clear_bar,
+    draw_bytes_bar,
+)
+
+_COMPRESS_EXTS = (
+    (".tar.gz", "gz"),
+    (".tgz", "gz"),
+    (".tar.bz2", "bz2"),
+    (".tbz2", "bz2"),
+    (".tar.xz", "xz"),
+    (".txz", "xz"),
+    (".tar.lzma", "xz"),
+    (".tlzma", "xz"),
+    (".tar", ""),
+)
+
+_UNSUPPORTED_EXTS = (".tar.zst", ".tzst", ".tar.lz4", ".tar.lz")
+
+_COMPRESSION_ARG_MAP = {
+    "gzip": "gz",
+    "bzip2": "bz2",
+    "xz": "xz",
+    "none": "",
+}
+
+
+def _compression_mode(filename: str) -> str:
+    """Return the tarfile compression suffix for *filename*'s extension."""
+    low = filename.lower()
+    for ext, comp in _COMPRESS_EXTS:
+        if low.endswith(ext):
+            return comp
+    for ext in _UNSUPPORTED_EXTS:
+        if low.endswith(ext):
+            raise ValueError(f"Compression format '{ext}' is not supported.")
+    return ""
+
+
+def _iter_entries(root: str, arcroot: str):
+    """Yield *(src_path, arcname)* for every entry under *root* in sorted order."""
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False, topdown=True):
+        rel = os.path.relpath(dirpath, root)
+        dirnames.sort()
+        arc_dir = arcroot if rel == "." else os.path.join(arcroot, rel)
+
+        yield (dirpath, arc_dir)
+
+        i = 0
+        while i < len(dirnames):
+            d = dirnames[i]
+            if os.path.islink(os.path.join(dirpath, d)):
+                yield (os.path.join(dirpath, d), os.path.join(arc_dir, d))
+                dirnames.pop(i)
+            else:
+                i += 1
+
+        for fname in sorted(filenames):
+            yield (os.path.join(dirpath, fname), os.path.join(arc_dir, fname))
+
+
+class _ReadCounter:
+    """File wrapper that calls on_read(n) with the byte count after each read."""
+
+    def __init__(self, fh, on_read):
+        self._fh = fh
+        self._on_read = on_read
+
+    def read(self, n=-1):
+        data = self._fh.read(n)
+        if data:
+            self._on_read(len(data))
+        return data
+
+    def __getattr__(self, name):
+        return getattr(self._fh, name)
+
+
+def _add_path(
+    tf: tarfile.TarFile,
+    src: str,
+    arcname: str,
+    on_read=None,
+) -> None:
+    """Add *src* to *tf* as *arcname*, stripping ownership info."""
+    try:
+        st = os.lstat(src)
+    except OSError:
+        return
+    m = st.st_mode
+    if stat.S_ISBLK(m) or stat.S_ISCHR(m) or stat.S_ISFIFO(m) or stat.S_ISSOCK(m):
+        return
+
+    try:
+        info = tf.gettarinfo(src, arcname=arcname)
+    except OSError:
+        return
+    info.uid = 0
+    info.gid = 0
+    info.uname = ""
+    info.gname = ""
+    if stat.S_ISREG(m):
+        try:
+            with open(src, "rb") as fh:
+                tf.addfile(info, _ReadCounter(fh, on_read) if on_read else fh)
+        except OSError:
+            pass
+    else:
+        tf.addfile(info)
+
+
+def _fix_permissions(rootfs_dir: str) -> None:
+    """Ensure all dirs and files in *rootfs_dir* are readable by owner."""
+    for dirpath, _dirs, files in os.walk(rootfs_dir):
+        with contextlib.suppress(OSError):
+            os.chmod(
+                dirpath,
+                os.stat(dirpath).st_mode | stat.S_IRUSR | stat.S_IXUSR,
+            )
+        for fname in files:
+            fpath = os.path.join(dirpath, fname)
+            try:
+                fst = os.lstat(fpath)
+                if stat.S_ISREG(fst.st_mode):
+                    mode = fst.st_mode
+                    if mode & (stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH):
+                        os.chmod(fpath, mode | stat.S_IRUSR | stat.S_IXUSR)
+                    else:
+                        os.chmod(fpath, mode | stat.S_IRUSR)
+            except OSError:
+                pass
+
+
+def command_backup(args) -> None:
+    """Archive an installed container to a tar file or stdout."""
+    container_name = args.container_name
+    output_path = getattr(args, "output", None)
+    compression_arg = getattr(args, "compression", None)
+    verbose = getattr(args, "verbose", False)
+
+    require_valid_name(container_name)
+
+    rootfs_dir = container_rootfs(container_name)
+    manifest_path = container_manifest(container_name)
+
+    if not os.path.isdir(rootfs_dir):
+        crit_error(f"container '{container_name}' does not exist.")
+        sys.exit(1)
+
+    if output_path is not None and not output_path:
+        crit_error("output file path cannot be empty.")
+        sys.exit(1)
+
+    if output_path:
+        if os.path.isdir(output_path):
+            crit_error(f"cannot write to '{output_path}' because this path is a directory.")
+            sys.exit(1)
+        if os.path.isfile(output_path):
+            crit_error(f"file '{output_path}' already exists. Please specify a different name.")
+            sys.exit(1)
+        if compression_arg is not None:
+            compression = _COMPRESSION_ARG_MAP[compression_arg]
+        else:
+            try:
+                compression = _compression_mode(output_path)
+            except ValueError as exc:
+                crit_error(str(exc).lower())
+                sys.exit(1)
+    else:
+        if sys.stdout.isatty():
+            crit_error("archive data cannot be printed to console. Please specify --output.")
+            sys.exit(1)
+        compression = _COMPRESSION_ARG_MAP[compression_arg] if compression_arg is not None else ""
+
+    with ContainerLock(container_name, exclusive=False, command="backup"):
+        # 1. Active sessions safety check
+        active_pids = session.get_active_chroot_pids(container_name)
+        if active_pids:
+            crit_error(f"Cannot backup container '{container_name}': It has active sessions (PIDs: {active_pids}).")
+            sys.exit(1)
+
+        # 2. Mount safety check: ensure no active mounts exist under rootfs
+        mounts = mount_manager.get_active_mounts(rootfs_dir)
+        if mounts:
+            crit_error(f"Cannot backup container '{container_name}': Active mounts detected under rootfs: {mounts}.")
+            sys.exit(1)
+
+        _run_backup(
+            container_name,
+            rootfs_dir,
+            manifest_path,
+            output_path,
+            compression,
+            verbose,
+        )
+
+
+def _run_backup(
+    container_name,
+    rootfs_dir,
+    manifest_path,
+    output_path,
+    compression,
+    verbose,
+):
+    log_info(f"Backing up '{container_name}'...")
+
+    if output_path:
+        log_info(f"Will write backup data to '{output_path}'.")
+    else:
+        log_info("Will write backup data to stdout.")
+
+    log_info("Fixing file permissions in rootfs...")
+    _fix_permissions(rootfs_dir)
+
+    arc_prefix = container_name
+    entries = []
+    if os.path.isfile(manifest_path):
+        entries.append((manifest_path, os.path.join(arc_prefix, "manifest.json")))
+    entries.extend(_iter_entries(rootfs_dir, os.path.join(arc_prefix, "rootfs")))
+
+    total_size = 0
+    for src, _arc in entries:
+        try:
+            st = os.lstat(src)
+        except OSError:
+            continue
+        if stat.S_ISREG(st.st_mode):
+            total_size += st.st_size
+
+    done_size = 0
+    log_info("Archiving the container...")
+
+    _last_shown = 0
+
+    def _draw_bar() -> None:
+        nonlocal _last_shown
+        draw_bytes_bar(done_size, total_size)
+        _last_shown = done_size
+
+    def _on_read(n: int) -> None:
+        nonlocal done_size
+        done_size += n
+        if done_size - _last_shown >= REDRAW_THRESHOLD_BYTES:
+            _draw_bar()
+
+    def _on_entry(arc: str) -> None:
+        if verbose:
+            log_info(f"Adding: '{arc}'")
+        _draw_bar()
+
+    try:
+        tar_mode = f"w:{compression}" if output_path else f"w|{compression}"
+        if output_path:
+            tf = tarfile.open(output_path, mode=tar_mode)  # type: ignore[call-overload]  # noqa: SIM115
+        else:
+            tf = tarfile.open(fileobj=sys.stdout.buffer, mode=tar_mode)  # type: ignore[call-overload]  # noqa: SIM115
+        with tf:
+            for src, arc in entries:
+                _add_path(tf, src, arc, on_read=_on_read)
+                _on_entry(arc)
+
+        clear_bar()
+        log_info("Finished backing up.")
+
+    except KeyboardInterrupt:
+        clear_bar()
+        log_error("Aborted by user.")
+        if output_path:
+            with contextlib.suppress(OSError):
+                os.remove(output_path)
+        sys.exit(1)
+    except (OSError, tarfile.TarError) as exc:
+        clear_bar()
+        log_error(f"Failed to create backup archive: {exc}")
+        if output_path:
+            with contextlib.suppress(OSError):
+                os.remove(output_path)
+        sys.exit(1)