linux-image-manager 2.1.0__py3-none-any.whl

lim/image/session.py

@@ -0,0 +1,190 @@
+"""Mount/unmount lifecycle for working on an image on a block device."""
+
+import time
+from pathlib import Path
+
+from lim import device as device_module
+from lim import runner, ui
+from lim.device import Device
+from lim.errors import LimError
+
+
+class ImageSession:
+    """Working folder, partition paths and (chroot) mounts for one device.
+
+    Call ``destructor()`` in a finally block: it unmounts and removes
+    everything best-effort, mirroring partially completed setups.
+    """
+
+    def __init__(self, device: Device) -> None:
+        self.device = device
+        self.working_folder: Path | None = None
+        self.boot_mount_path: Path | None = None
+        self.root_mount_path: Path | None = None
+        self.boot_partition_path = device.partition(1)
+        self.root_partition_path = device.partition(2)
+        # Overridden by decrypt_root() when the root partition is LUKS.
+        self.root_mapper_path = self.root_partition_path
+        self.root_mapper_name: str | None = None
+        self.boot_partition_uuid: str | None = None
+        self.root_partition_uuid: str | None = None
+
+    def make_working_folder(self) -> None:
+        # Mount points must live on the root fs; mkdir() fails on collisions.
+        self.working_folder = Path(f"/tmp/linux-image-manager-{int(time.time())}")  # noqa: S108
+        ui.info(f"Create temporary working folder in {self.working_folder}")
+        self.working_folder.mkdir(parents=True)
+
+    def make_mount_folders(self) -> None:
+        if self.working_folder is None:
+            self.make_working_folder()
+        ui.info("Preparing mount paths...")
+        self.boot_mount_path = self.working_folder / "boot"
+        self.root_mount_path = self.working_folder / "root"
+        self.boot_mount_path.mkdir()
+        self.root_mount_path.mkdir()
+
+    def root_is_luks(self) -> bool:
+        return device_module.blkid_value(self.root_partition_path, "TYPE") == "crypto_LUKS"
+
+    def read_partition_uuids(self) -> None:
+        """Fetch partition UUIDs via blkid; derive the LUKS mapper name if unset."""
+        self.root_partition_uuid = device_module.blkid_value(
+            self.root_partition_path, "UUID"
+        )
+        self.boot_partition_uuid = device_module.blkid_value(
+            self.boot_partition_path, "UUID"
+        )
+        if self.root_mapper_name is None and self.root_is_luks():
+            # Same deterministic name decrypt_root() would have used.
+            self.root_mapper_name = f"linux-image-manager-{self.root_partition_uuid}"
+            self.root_mapper_path = f"/dev/mapper/{self.root_mapper_name}"
+
+    def decrypt_root(self) -> None:
+        if not self.root_is_luks():
+            return
+        self.root_partition_uuid = device_module.blkid_value(
+            self.root_partition_path, "UUID"
+        )
+        self.root_mapper_name = f"linux-image-manager-{self.root_partition_uuid}"
+        self.root_mapper_path = f"/dev/mapper/{self.root_mapper_name}"
+        ui.info(f"Decrypting of {self.root_partition_path} is neccessary...")
+        runner.run(
+            [
+                "cryptsetup",
+                "-v",
+                "luksOpen",
+                self.root_partition_path,
+                self.root_mapper_name,
+            ],
+            sudo=True,
+        )
+
+    def mount_partitions(self) -> None:
+        if self.boot_mount_path is None:
+            raise LimError("Mount folders are not prepared yet.")
+        ui.info("Mount boot and root partition...")
+        runner.run(
+            ["mount", "-v", self.boot_partition_path, str(self.boot_mount_path)],
+            sudo=True,
+        )
+        runner.run(
+            ["mount", "-v", self.root_mapper_path, str(self.root_mount_path)], sudo=True
+        )
+        ui.info("Setting uuid variables...")
+        self.read_partition_uuids()
+        ui.info("The following mounts refering this setup exist:")
+        runner.run(["findmnt", "-R", str(self.working_folder)], check=False)
+
+    def mount_chroot_binds(self) -> None:
+        ui.info("Mount chroot environments...")
+        root = self.root_mount_path
+        runner.run(["mount", "--bind", str(self.boot_mount_path), f"{root}/boot"], sudo=True)
+        runner.run(["mount", "--bind", "/dev", f"{root}/dev"], sudo=True)
+        runner.run(["mount", "--bind", "/sys", f"{root}/sys"], sudo=True)
+        runner.run(["mount", "--bind", "/proc", f"{root}/proc"], sudo=True)
+        runner.run(["mount", "--bind", "/dev/pts", f"{root}/dev/pts"], sudo=True)
+
+    def copy_qemu(self) -> None:
+        ui.info("Copy qemu binary...")
+        runner.run(
+            ["cp", "-v", "/usr/bin/qemu-arm-static", f"{self.root_mount_path}/usr/bin/"],
+            sudo=True,
+        )
+
+    def copy_resolv_conf(self) -> None:
+        ui.info("Copy resolv.conf...")
+        copied = runner.run(
+            [
+                "cp",
+                "--remove-destination",
+                "-v",
+                "/etc/resolv.conf",
+                f"{self.root_mount_path}/etc/",
+            ],
+            sudo=True,
+            check=False,
+        )
+        if copied.returncode != 0:
+            ui.warning("Failed. Probably there is no internet connection available.")
+
+    def _umount(self, path: str, *, lazy: bool = False) -> None:
+        flags = ["-lv"] if lazy else ["-v"]
+        result = runner.run(["umount", *flags, path], sudo=True, check=False)
+        if result.returncode != 0:
+            ui.warning(f"Umounting {path} failed!")
+
+    def _rmdir(self, path: Path | None) -> None:
+        if path is None:
+            return
+        result = runner.run(["rmdir", "-v", str(path)], sudo=True, check=False)
+        if result.returncode != 0:
+            ui.warning(f"Removing {path} failed!")
+
+    def destructor(self) -> None:
+        ui.info("Cleaning up...")
+        ui.info("Unmounting everything...")
+        root = self.root_mount_path
+        if root is not None:
+            self._umount(f"{root}/dev/pts", lazy=True)
+            self._umount(f"{root}/dev", lazy=True)
+            self._umount(f"{root}/proc")
+            self._umount(f"{root}/sys")
+            self._umount(f"{root}/boot")
+            self._umount(str(root))
+        if self.boot_mount_path is not None:
+            self._umount(str(self.boot_mount_path))
+        ui.info("Deleting mount folders...")
+        self._rmdir(self.root_mount_path)
+        self._rmdir(self.boot_mount_path)
+        self._rmdir(self.working_folder)
+        if self.root_mapper_name and self.root_is_luks():
+            ui.info(f"Trying to close decrypted {self.root_mapper_name}...")
+            closed = runner.run(
+                ["cryptsetup", "-v", "luksClose", self.root_mapper_name],
+                sudo=True,
+                check=False,
+            )
+            if closed.returncode != 0:
+                ui.warning("Failed.")
+
+
+def chroot_bash(root_mount_path: Path | str, script: str, error_msg: str | None = None) -> None:
+    """Run a bash script inside the image via chroot."""
+    runner.run(
+        ["chroot", str(root_mount_path), "/bin/bash"],
+        input_text=script,
+        sudo=True,
+        error_msg=error_msg,
+    )
+
+
+def install_packages(distribution: str, root_mount_path: Path, package_names: str) -> None:
+    """Install packages inside the image with the distribution's package manager."""
+    ui.info(f"Installing {package_names}...")
+    if distribution in ("arch", "manjaro"):
+        chroot_bash(root_mount_path, f"pacman --noconfirm -S --needed {package_names}")
+    elif distribution in ("moode", "retropie"):
+        chroot_bash(root_mount_path, f"yes | apt install {package_names}")
+    else:
+        raise LimError("Package manager not supported.")

lim/image/setup.py

@@ -0,0 +1,96 @@
+"""Interactive Linux image setup: download, verify, transfer, configure.
+
+Reference for encrypted Raspberry Pi images:
+https://wiki.polaire.nl/doku.php?id=archlinux-raspberry-encrypted
+"""
+
+import pwd
+from pathlib import Path
+
+from lim import device as device_module
+from lim import system, ui
+from lim.errors import LimError
+from lim.image import choosers, transfer, verify
+from lim.image.plan import ImagePlan
+from lim.image.raspberry import configure_raspberry_image
+from lim.image.session import ImageSession
+
+
+def _prepare_image_folder(plan: ImagePlan) -> None:
+    ui.info("Configure user...")
+    origin_username = ui.ask("Please type in a valid working username:")
+    try:
+        pwd.getpwnam(origin_username)
+    except KeyError:
+        raise LimError(f"User {origin_username} doesn't exist.") from None
+
+    ui.info("Image routine starts...")
+    plan.image_folder = Path(f"/home/{origin_username}/Software/Images")
+    ui.info(f'The images will be stored in "{plan.image_folder}".')
+    if not plan.image_folder.is_dir():
+        ui.info(f'Folder "{plan.image_folder}" doesn\'t exist. It will be created now.')
+        plan.image_folder.mkdir(parents=True)
+
+
+def _select_unmounted_device() -> device_module.Device:
+    device = device_module.select_device()
+    if device_module.is_mounted(device.path):
+        raise LimError(
+            f'Device {device.path} is allready mounted. '
+            f'Umount with "umount {device.path}*".'
+        )
+    return device
+
+
+def _choose_and_verify_image(plan: ImagePlan) -> None:
+    plan.operation_system = ui.ask(
+        "Which operation system would you like to use [linux,windows,...]?"
+    )
+    if plan.operation_system == "linux":
+        choosers.choose_linux_image(plan)
+        plan.encrypt_system = ui.confirm("Should the system be encrypted?")
+        ui.info("Generating os-image...")
+        transfer.download_image(plan)
+    else:
+        choosers.choose_local_image(plan)
+
+    ui.info("Verifying image...")
+    ui.info("Verifying checksum...")
+    if plan.image_checksum is None and plan.download_url is not None:
+        plan.image_checksum = verify.resolve_checksum(plan.download_url)
+    verify.verify_checksum(plan.image_path, plan.image_checksum)
+    if plan.download_url is not None:
+        verify.verify_signature(plan.download_url, plan.image_path, plan.image_folder)
+
+
+def run_setup() -> None:
+    ui.info("Setupscript for images started...")
+    ui.info("Checking if root...")
+    if not system.is_root():
+        raise LimError("This script must be executed as root!")
+
+    plan = ImagePlan()
+    _prepare_image_folder(plan)
+    device = _select_unmounted_device()
+    _choose_and_verify_image(plan)
+
+    session = ImageSession(device)
+    try:
+        session.make_working_folder()
+        session.make_mount_folders()
+
+        plan.root_filesystem = ui.ask(
+            "Which filesystem should be used? E.g.:btrfs,ext4... (none):"
+        )
+
+        if ui.confirm(f"Should the image be transfered to {device.path}?"):
+            transfer.transfer_image(plan, session)
+        else:
+            ui.info("Skipping image transfer...")
+
+        if plan.raspberry_pi_version:
+            configure_raspberry_image(plan, session)
+    finally:
+        session.destructor()
+
+    ui.success("Setup successfull :)")

lim/image/transfer.py

@@ -0,0 +1,140 @@
+"""Download the selected image and transfer it onto the target device."""
+
+from pathlib import Path
+
+from lim import device as device_module
+from lim import runner, ui
+from lim.errors import LimError
+from lim.image.plan import DEFAULT_BOOT_SIZE, ImagePlan
+from lim.image.session import ImageSession
+
+
+def download_image(plan: ImagePlan) -> None:
+    if ui.confirm("Should the image download be forced?"):
+        if plan.image_path.is_file():
+            ui.info(f"Removing image {plan.image_path}.")
+            plan.image_path.unlink()
+        else:
+            ui.info(
+                "Forcing download wasn't neccessary. "
+                f"File {plan.image_path} doesn't exist."
+            )
+
+    ui.info("Start Download procedure...")
+    if plan.image_path.is_file():
+        ui.info("Image exist local. Download skipped.")
+        return
+    ui.info(f'Image "{plan.image_name}" doesn\'t exist under local path "{plan.image_path}".')
+    ui.info(f'Image "{plan.image_name}" gets downloaded from "{plan.download_url}"...')
+    runner.run(
+        ["wget", plan.download_url, "-O", str(plan.image_path)],
+        error_msg=f'Download from "{plan.download_url}" failed.',
+    )
+
+
+def arch_partition_input(boot_size: str) -> str:
+    """Fdisk answers: FAT32 boot partition of boot_size plus root partition."""
+    return (
+        "o\n"          # clear out any partitions on the drive
+        "p\n"          # list partitions (should be empty)
+        "n\np\n1\n\n"  # new primary partition 1, default start sector
+        f"{boot_size}\n"
+        "t\nc\n"       # set partition 1 to type W95 FAT32 (LBA)
+        "n\np\n2\n\n\n"  # new primary partition 2 over the remaining space
+        "w\n"          # write partition table
+    )
+
+
+def decompress_command(image_path: Path) -> list[str]:
+    """Build the command that streams the raw image to stdout for dd."""
+    suffix = image_path.suffix
+    if suffix == ".zip":
+        return ["unzip", "-p", str(image_path)]
+    if suffix == ".gz":
+        return ["gunzip", "-c", str(image_path)]
+    if suffix == ".iso":
+        return ["pv", str(image_path)]
+    if suffix == ".xz":
+        return ["unxz", "-c", str(image_path)]
+    raise LimError(f'Image transfer for "{image_path.name}" is not supported yet!')
+
+
+def _luks_format_root(plan: ImagePlan, session: ImageSession) -> None:
+    luks_format = [
+        "cryptsetup", "-v", "luksFormat",
+        "-c", "aes-xts-plain64", "-s", "512", "-h", "sha512",
+        "--use-random", "-i", "1000",
+    ]
+    if plan.luks_memory_cost:
+        ui.info(
+            f"Formating {session.root_partition_path} with LUKS "
+            f"with --pbkdf-memory set to {plan.luks_memory_cost}"
+        )
+        luks_format += ["--pbkdf-memory", plan.luks_memory_cost]
+    else:
+        ui.info(f"Formating {session.root_partition_path} with LUKS")
+    runner.run([*luks_format, session.root_partition_path], sudo=True)
+
+
+def transfer_arch_image(plan: ImagePlan, session: ImageSession) -> None:
+    boot_size = plan.boot_size or DEFAULT_BOOT_SIZE
+    ui.info(f"The boot partition will be set to {boot_size}.")
+    ui.info("Creating partitions...")
+    runner.run(
+        ["fdisk", session.device.path],
+        input_text=arch_partition_input(boot_size),
+        sudo=True,
+    )
+
+    ui.info("Format boot partition...")
+    runner.run(["mkfs.vfat", session.boot_partition_path], sudo=True)
+
+    if plan.encrypt_system:
+        _luks_format_root(plan, session)
+        session.decrypt_root()
+
+    ui.info("Format root partition...")
+    runner.run([f"mkfs.{plan.root_filesystem}", "-f", session.root_mapper_path], sudo=True)
+    session.mount_partitions()
+
+    ui.info("Root files will be transfered to device...")
+    runner.run(
+        ["bsdtar", "-xpf", str(plan.image_path), "-C", str(session.root_mount_path)],
+        sudo=True,
+    )
+    runner.sync_disks()
+
+    ui.info("Boot files will be transfered to device...")
+    boot_source = session.root_mount_path / "boot"
+    for entry in sorted(boot_source.iterdir()):
+        runner.run(["mv", "-v", str(entry), str(session.boot_mount_path)], sudo=True)
+
+
+def transfer_image(plan: ImagePlan, session: ImageSession) -> None:
+    if ui.confirm(f"Should the partition table of {session.device.path} be deleted?"):
+        ui.info("Deleting...")
+        runner.run(["wipefs", "-a", session.device.path], sudo=True)
+    else:
+        ui.info("Skipping partition table deletion...")
+
+    device_module.overwrite_device(session.device)
+
+    ui.info("Starting image transfer...")
+    if plan.distribution == "arch":
+        transfer_arch_image(plan, session)
+        return
+    blocksize = session.device.optimal_blocksize
+    ui.info(f"Transfering {plan.image_path.suffix} file...")
+    runner.pipeline(
+        decompress_command(plan.image_path),
+        [
+            "dd",
+            f"of={session.device.path}",
+            f"bs={blocksize}",
+            "conv=fsync",
+            "status=progress",
+        ],
+        sudo_last=True,
+        error_msg=f"DD {plan.image_path} to {session.device.path} failed.",
+    )
+    runner.sync_disks()

lim/image/verify.py

@@ -0,0 +1,100 @@
+"""Image integrity (checksums) and authenticity (GPG signatures) checks."""
+
+import hashlib
+import re
+from pathlib import Path
+
+from lim import runner, ui
+from lim.errors import LimError
+
+ALGORITHM_BY_DIGEST_LENGTH = {
+    32: "md5",
+    40: "sha1",
+    64: "sha256",
+    128: "sha512",
+}
+
+
+def url_exists(url: str) -> bool:
+    return runner.succeeds(["wget", "-q", "--method=HEAD", url])
+
+
+def resolve_checksum(download_url: str) -> str | None:
+    """Try to fetch a published checksum next to the image download."""
+    for extension in ("sha1", "sha512", "md5"):
+        checksum_url = f"{download_url}.{extension}"
+        ui.info(
+            "Image Checksum is not defined. "
+            f"Try to download image signature from {checksum_url}."
+        )
+        if url_exists(checksum_url):
+            content = runner.output(["wget", checksum_url, "-q", "-O", "-"])
+            checksum = content.split()[0] if content.split() else ""
+            if checksum:
+                ui.info(f"Defined image_checksum as {checksum}")
+                return checksum
+        ui.warning(f"No checksum found under {checksum_url}.")
+    return None
+
+
+def verify_checksum(image_path: str | Path, checksum: str | None) -> None:
+    """Verify the image against an md5/sha1/sha256/sha512 hex checksum."""
+    if not checksum:
+        ui.warning("No checksum is defined. Skipping checksum verification.")
+        return
+    algorithm = ALGORITHM_BY_DIGEST_LENGTH.get(len(checksum))
+    if algorithm is None:
+        raise LimError(
+            f"Checksum '{checksum}' has no recognized digest length "
+            "(expected md5, sha1, sha256 or sha512)."
+        )
+    ui.info(f"Checking {algorithm} checksum...")
+    digest = hashlib.new(algorithm)
+    with Path(image_path).open("rb") as handle:
+        while chunk := handle.read(1024 * 1024):
+            digest.update(chunk)
+    if digest.hexdigest() != checksum.lower():
+        raise LimError("Verification failed. HINT: Force the download of the image.")
+    ui.info(f"{algorithm} checksum verified.")
+
+
+def verify_signature(download_url: str, image_path: str | Path, image_folder: Path) -> None:
+    """Best-effort GPG signature verification of the downloaded image."""
+    ui.info("Note: Checksums verify integrity but do not confirm authenticity.")
+    ui.info(
+        "Proceeding to signature verification, "
+        "which ensures the file comes from a trusted source."
+    )
+    signature_url = f"{download_url}.sig"
+    ui.info(f"Attempting to download the image signature from: {signature_url}")
+    if not url_exists(signature_url):
+        ui.warning(f"No signature found under {signature_url}.")
+        return
+
+    signature_path = image_folder / (Path(str(image_path)).name + ".sig")
+    if not runner.succeeds(["wget", "-q", "-O", str(signature_path), signature_url]):
+        ui.warning("Failed to download the signature file.")
+        return
+
+    ui.info("Extract the key ID from the signature file")
+    verification = runner.output(
+        ["gpg", "--status-fd", "1", "--verify", str(signature_path), str(image_path)],
+        check=False,
+    )
+    missing_keys = re.findall(r"NO_PUBKEY (\S+)", verification)
+    if missing_keys:
+        key_id = missing_keys[-1]
+        if runner.succeeds(["gpg", "--list-keys", key_id]):
+            ui.info(f"Key {key_id} already in keyring.")
+        else:
+            ui.info("Import the public key")
+            runner.run(
+                ["gpg", "--keyserver", "keyserver.ubuntu.com", "--recv-keys", key_id],
+                check=False,
+            )
+
+    ui.info("Verify the signature")
+    if runner.succeeds(["gpg", "--verify", str(signature_path), str(image_path)]):
+        ui.info("Signature verification succeeded.")
+    else:
+        ui.warning("Signature verification failed.")

lim/luks.py

@@ -0,0 +1,80 @@
+"""LUKS key management plus crypttab/fstab bookkeeping."""
+
+import re
+from pathlib import Path
+
+from lim import fsutil, runner, ui
+from lim.errors import LimError
+
+LUKS_KEY_DIRECTORY = Path("/etc/luks-keys")
+CRYPTTAB_PATH = Path("/etc/crypttab")
+FSTAB_PATH = Path("/etc/fstab")
+
+
+def luks_uuid(partition_path: str) -> str:
+    dump = runner.output(["cryptsetup", "luksDump", partition_path], sudo=True)
+    match = re.search(r"UUID:\s*(\S+)", dump)
+    if not match:
+        raise LimError(f"Could not read LUKS UUID of {partition_path}.")
+    return match.group(1)
+
+
+def create_luks_key_and_update_crypttab(
+    mapper_name: str,
+    partition_path: str,
+    *,
+    key_directory: Path = LUKS_KEY_DIRECTORY,
+    crypttab_path: Path = CRYPTTAB_PATH,
+) -> None:
+    """Generate a random keyfile, register it with LUKS and /etc/crypttab."""
+    ui.info("Creating luks-key-directory...")
+    key_directory.mkdir(parents=True, exist_ok=True)
+    secret_key_path = key_directory / f"{mapper_name}.keyfile"
+    ui.info(f"Generate secret key under: {secret_key_path}")
+    if secret_key_path.exists():
+        ui.warning("File already exists. Overwriting!")
+    runner.run(
+        ["dd", "if=/dev/urandom", f"of={secret_key_path}", "bs=512", "count=8"],
+        sudo=True,
+    )
+    runner.sync_disks()
+
+    ui.info("Opening and closing device to verify that everything works fine...")
+    closed = runner.run(
+        ["cryptsetup", "-v", "luksClose", mapper_name], sudo=True, check=False
+    )
+    if closed.returncode != 0:
+        ui.info(f"No need to luksClose {mapper_name}. Device isn't open.")
+    runner.run(
+        ["cryptsetup", "luksAddKey", partition_path, str(secret_key_path)], sudo=True
+    )
+    runner.run(
+        [
+            "cryptsetup",
+            "-v",
+            "luksOpen",
+            partition_path,
+            mapper_name,
+            f"--key-file={secret_key_path}",
+        ],
+        sudo=True,
+    )
+    runner.run(["cryptsetup", "-v", "luksClose", mapper_name], sudo=True)
+
+    ui.info("Reading UUID...")
+    uuid = luks_uuid(partition_path)
+    entry = f"{mapper_name} UUID={uuid} {secret_key_path} luks"
+    ui.info("Adding crypttab entry...")
+    fsutil.ensure_line_in_file(entry, crypttab_path)
+    ui.info(f"The file {crypttab_path} contains now the following:")
+    print(crypttab_path.read_text())
+
+
+def update_fstab(
+    mapper_path: str, mount_path: str, *, fstab_path: Path = FSTAB_PATH
+) -> None:
+    entry = f"{mapper_path} {mount_path} btrfs   defaults   0       2"
+    ui.info("Adding fstab entry...")
+    fsutil.ensure_line_in_file(entry, fstab_path)
+    ui.info(f"The file {fstab_path} contains now the following:")
+    print(fstab_path.read_text())

lim/packages.py

@@ -0,0 +1,18 @@
+"""Reads package collections from configuration/packages/."""
+
+from lim import config
+from lim.errors import LimError
+
+
+def get_packages(*collections: str) -> list[str]:
+    """Package names from the given collections, comments stripped."""
+    names: list[str] = []
+    for collection in collections:
+        path = config.PACKAGE_PATH / f"{collection}.txt"
+        if not path.is_file():
+            raise LimError(f"Package collection {path} does not exist.")
+        for line in path.read_text().splitlines():
+            name = line.split("#", 1)[0].strip()
+            if name:
+                names.append(name)
+    return names