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

lim/__init__.py

@@ -0,0 +1,3 @@
+"""Linux Image Manager — administration tool for Linux images and encrypted storage."""
+
+__version__ = "1.0.0"

lim/catalog.py

@@ -0,0 +1,31 @@
+"""Read-only access to the image catalog (distributions.yml in the package)."""
+
+from functools import cache
+
+import yaml
+
+from lim import config
+
+CATALOG_PATH = config.CATALOG_PATH
+
+
+@cache
+def _load() -> dict:
+    with CATALOG_PATH.open() as handle:
+        return yaml.safe_load(handle)
+
+
+def arch_rpi_images() -> dict[str, dict[str, str]]:
+    return _load()["arch_rpi_images"]
+
+
+def manjaro_gnome_releases() -> dict[str, dict[str, str]]:
+    return _load()["manjaro_gnome_releases"]
+
+
+def retropie_images() -> dict[str, dict[str, str]]:
+    return _load()["retropie_images"]
+
+
+def mkinitcpio_modules_by_rpi() -> dict[str, str]:
+    return _load()["mkinitcpio_modules_by_rpi"]

lim/cli.py

@@ -0,0 +1,167 @@
+"""Command line interface: `lim --type <command>`."""
+
+import argparse
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from lim import system, ui
+from lim.data import crypt, sync
+from lim.errors import LimError
+from lim.image import backup, chroot
+from lim.image import setup as image_setup
+from lim.storage import raid1, single_drive
+
+
+@dataclass(frozen=True)
+class Command:
+    func: Callable[[], None]
+    description: str
+    needs_root: bool
+
+
+COMMANDS: dict[str, Command] = {
+    "image": Command(
+        image_setup.run_setup,
+        "Linux Image Setup:\n"
+        "  - Creates partitions and formats them.\n"
+        "  - Transfers the Linux image file to the device.\n"
+        "  - Configures boot and root partitions.",
+        needs_root=True,
+    ),
+    "single": Command(
+        single_drive.setup,
+        "Single Drive Encryption Setup:\n"
+        "  - Sets up disk encryption using LUKS on one drive.\n"
+        "  - Configures a Btrfs file system for secure storage.",
+        needs_root=True,
+    ),
+    "raid1": Command(
+        raid1.setup,
+        "RAID1 Encryption Setup:\n"
+        "  - Configures a virtual RAID1 with two drives.\n"
+        "  - Uses LUKS encryption and a Btrfs RAID1 file system for redundancy.",
+        needs_root=True,
+    ),
+    "backup": Command(
+        backup.run_backup,
+        "Backup Image Setup:\n"
+        "  - Creates an image backup from a memory device to a file.\n"
+        "  - Uses dd to transfer the image from the specified device to an image file.",
+        needs_root=True,
+    ),
+    "chroot": Command(
+        chroot.run_chroot,
+        "Chroot Environment Setup:\n"
+        "  - Mounts partitions and configures the chroot environment for a Linux image.\n"
+        "  - Provides a shell within the Linux image for system maintenance.",
+        needs_root=True,
+    ),
+    "mount": Command(
+        single_drive.mount,
+        "Mount Encrypted Storage:\n"
+        "  - Unlocks a LUKS partition and mounts it.",
+        needs_root=True,
+    ),
+    "umount": Command(
+        single_drive.umount,
+        "Unmount Encrypted Storage:\n"
+        "  - Unmounts a LUKS partition and closes the mapper.",
+        needs_root=True,
+    ),
+    "single-boot": Command(
+        single_drive.mount_on_boot,
+        "Single Drive Automount Setup:\n"
+        "  - Creates a LUKS keyfile and registers it in crypttab and fstab.",
+        needs_root=True,
+    ),
+    "raid1-boot": Command(
+        raid1.mount_on_boot,
+        "RAID1 Automount Setup:\n"
+        "  - Creates LUKS keyfiles for both drives and registers them in crypttab/fstab.",
+        needs_root=True,
+    ),
+    "unlock": Command(
+        crypt.unlock,
+        "Unlock Data:\n"
+        "  - Decrypts the encfs data store into the decrypted folder.",
+        needs_root=False,
+    ),
+    "lock": Command(
+        crypt.lock,
+        "Lock Data:\n"
+        "  - Unmounts the decrypted encfs folder.",
+        needs_root=False,
+    ),
+    "import": Command(
+        sync.import_from_system,
+        "Import Data:\n"
+        "  - Copies personal data from the system into the encrypted store.",
+        needs_root=False,
+    ),
+    "export": Command(
+        sync.export_to_system,
+        "Export Data:\n"
+        "  - Copies personal data from the encrypted store back to the system.",
+        needs_root=False,
+    ),
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    epilog_lines = ["Available script types:"]
+    epilog_lines += [
+        f"  {name:<12} - {command.description.splitlines()[0].rstrip(':')}"
+        for name, command in COMMANDS.items()
+    ]
+    parser = argparse.ArgumentParser(
+        prog="lim",
+        description="Linux Image Manager — manages Linux images and encrypted storage.",
+        epilog="\n".join(epilog_lines),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--type",
+        required=True,
+        choices=list(COMMANDS.keys()),
+        help="Select the command to execute.",
+    )
+    parser.add_argument(
+        "--auto-confirm",
+        action="store_true",
+        help="Automatically confirm execution without prompting the user.",
+    )
+    parser.add_argument(
+        "--extra",
+        nargs=argparse.REMAINDER,
+        default=[],
+        help="Deprecated, ignored. Former extra parameters for the shell scripts.",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = build_parser().parse_args(argv)
+    command = COMMANDS[args.type]
+
+    if args.extra:
+        ui.warning("--extra is deprecated and ignored.")
+    if command.needs_root:
+        system.ensure_root()
+
+    ui.header()
+    ui.info(f"Selected command: {args.type}")
+    ui.info("Description:")
+    print(command.description)
+
+    try:
+        if not args.auto_confirm:
+            input("Press Enter to execute or Ctrl+C to cancel...")
+        command.func()
+    except LimError as exc:
+        ui.error(f"{exc} -> Leaving program.")
+        sys.exit(1)
+    except KeyboardInterrupt:
+        print()
+        ui.error("Execution aborted by user.")
+        sys.exit(1)

lim/config.py

@@ -0,0 +1,18 @@
+"""Package and repository paths shared by all modules.
+
+Configuration and the image catalog ship inside the package so that
+wheel installs work; the encfs data store stays repository-relative.
+"""
+
+from pathlib import Path
+
+PACKAGE_ROOT = Path(__file__).resolve().parent
+CONFIGURATION_PATH = PACKAGE_ROOT / "configuration"
+PACKAGE_PATH = CONFIGURATION_PATH / "packages"
+CATALOG_PATH = PACKAGE_ROOT / "distributions.yml"
+
+REPOSITORY_PATH = PACKAGE_ROOT.parent
+ENCRYPTED_PATH = REPOSITORY_PATH / ".encrypted"
+DECRYPTED_PATH = REPOSITORY_PATH / "decrypted"
+DATA_PATH = DECRYPTED_PATH / "data"
+BACKUP_PATH = DECRYPTED_PATH / "backup"

lim/configuration/packages/general.txt

@@ -0,0 +1,6 @@
+# This packages will be used in all setup scripts
+nano
+tree
+htop
+git
+sudo

lim/configuration/packages/server/luks.txt

@@ -0,0 +1,8 @@
+# Packages to install LUKS on servers
+rsync
+base-devel
+uboot-tools
+dropbear
+mkinitcpio-utils
+mkinitcpio-netconf
+mkinitcpio-dropbear

lim/data/crypt.py

@@ -0,0 +1,24 @@
+"""Lock/unlock the encfs-encrypted data directory."""
+
+from lim import config, runner, ui
+
+
+def unlock() -> None:
+    ui.info(f"Unlocking directory {config.DECRYPTED_PATH}...")
+    if not config.DECRYPTED_PATH.is_dir():
+        ui.info(f"Creating directory {config.DECRYPTED_PATH}...")
+        config.DECRYPTED_PATH.mkdir()
+    ui.info(f"Decrypting directory {config.ENCRYPTED_PATH} to {config.DECRYPTED_PATH}...")
+    runner.run(["encfs", str(config.ENCRYPTED_PATH), str(config.DECRYPTED_PATH)])
+    print("ATTENTION: DATA IS NOW DECRYPTED!")
+
+
+def lock() -> None:
+    ui.info(f"Locking directory {config.DECRYPTED_PATH}...")
+    runner.run(
+        ["fusermount", "-u", str(config.DECRYPTED_PATH)],
+        error_msg="Unmounting failed.",
+    )
+    ui.info("Data is now encrypted.")
+    ui.info(f"Removing directory {config.DECRYPTED_PATH}...")
+    config.DECRYPTED_PATH.rmdir()

lim/data/sync.py

@@ -0,0 +1,135 @@
+"""Import personal data from the system into the encrypted store, or export it back."""
+
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from lim import config, runner, system, ui
+from lim.data import crypt
+from lim.errors import LimError
+
+# Paths relative to $HOME; trailing "/" marks a directory tree.
+BACKUP_ITEMS = [
+    ".ssh/",
+    ".gitconfig",
+    ".atom/config.cson",
+    ".projectlibre/projectlibre.conf",
+    ".local/share/rhythmbox/rhythmdb.xml",
+    ".config/keepassxc/keepassxc.ini",
+    "Documents/certificates/",
+    "Documents/security/",
+    "Documents/identity/",
+    "Documents/health/",
+    "Documents/licenses/",
+]
+
+
+@dataclass(frozen=True)
+class SyncOperation:
+    source: str
+    destination: str
+    backup_dir: str
+    is_directory: bool
+
+
+def build_sync_plan(
+    mode: str,
+    home: Path,
+    data_path: Path,
+    backup_folder: Path,
+) -> list[SyncOperation]:
+    """One rsync operation per existing backup item; missing sources are skipped."""
+    operations = []
+    for item in BACKUP_ITEMS:
+        is_directory = item.endswith("/")
+        system_path = home / item
+        # The store mirrors the absolute system path below DATA_PATH.
+        data_path_item = Path(f"{data_path}{system_path}")
+        if mode == "export":
+            source, destination = data_path_item, system_path
+        elif mode == "import":
+            source, destination = system_path, data_path_item
+        else:
+            raise LimError(f"Unknown sync mode: {mode}")
+        ui.info(f"{mode.capitalize()} data from {source} to {destination}...")
+        if not (source.is_file() or source.is_dir()):
+            ui.warning(f"{source} doesn't exist. Copying data is not possible.")
+            continue
+        if is_directory:
+            backup_dir = Path(f"{backup_folder}{system_path}")
+        else:
+            backup_dir = Path(f"{backup_folder}{system_path}").parent
+        operations.append(
+            SyncOperation(
+                source=f"{source}/" if is_directory else str(source),
+                destination=f"{destination}/" if is_directory else str(destination),
+                backup_dir=str(backup_dir),
+                is_directory=is_directory,
+            )
+        )
+    return operations
+
+
+def rsync_command(operation: SyncOperation) -> list[str]:
+    command = ["rsync", "-abcEPuvW"]
+    if operation.is_directory:
+        command.append("--delete")
+    command += [f"--backup-dir={operation.backup_dir}", operation.source, operation.destination]
+    return command
+
+
+def execute_sync_plan(operations: list[SyncOperation]) -> None:
+    for operation in operations:
+        Path(operation.backup_dir).mkdir(parents=True, exist_ok=True)
+        destination_dir = (
+            Path(operation.destination)
+            if operation.is_directory
+            else Path(operation.destination).parent
+        )
+        destination_dir.mkdir(parents=True, exist_ok=True)
+        if not operation.is_directory and Path(operation.destination).is_file():
+            ui.info("The destination file already exists!")
+            ui.info("Difference:")
+            runner.run(
+                ["diff", operation.destination, operation.source], check=False
+            )
+        runner.run(rsync_command(operation))
+
+
+def ensure_unlocked() -> None:
+    mounts = runner.output(["mount"], check=False)
+    if str(config.DECRYPTED_PATH) not in mounts:
+        ui.info(
+            f"The decrypted folder {config.DECRYPTED_PATH} is locked. "
+            "You need to unlock it!"
+        )
+        crypt.unlock()
+
+
+def import_from_system(mode: str = "import") -> None:
+    ensure_unlocked()
+    backup_folder = (
+        config.BACKUP_PATH / mode / time.strftime("%Y%m%d%H%M%S")
+    )
+    backup_folder.mkdir(parents=True, exist_ok=True)
+    operations = build_sync_plan(
+        mode, system.real_home(), config.DATA_PATH, backup_folder
+    )
+    execute_sync_plan(operations)
+
+
+def export_to_system() -> None:
+    import_from_system(mode="export")
+    user = system.real_user()
+    home = system.real_home()
+    ui.info("Setting right permissions for imported files...")
+    try:
+        (home / ".ssh").chmod(0o700)
+        for child in (home / ".ssh").rglob("*"):
+            child.chmod(0o700 if child.is_dir() else 0o600)
+    except OSError as exc:
+        raise LimError(f"Failed to set correct ssh permissions: {exc}") from exc
+    # Best effort without privilege escalation, like the original script.
+    chowned = runner.run(["chown", "-R", f"{user}:{user}", str(home)], check=False)
+    if chowned.returncode != 0:
+        ui.warning(f'Not all files could be owned by user "{user}"...')

lim/device.py

@@ -0,0 +1,130 @@
+"""Block-device selection and low-level device helpers."""
+
+import stat as stat_module
+from dataclasses import dataclass
+from pathlib import Path
+
+from lim import runner, ui
+from lim.errors import LimError
+
+SYS_BLOCK_PATH = Path("/sys/block")
+
+PARTITION_TABLE_INFO = """\
+##########################################################################################
+Note on Partition Table Deletion:
+---------------------------------------------
+• MBR (Master Boot Record):
+  - Typically occupies the first sector (512 bytes), i.e., 1 block.
+
+• GPT (GUID Partition Table):
+  - Uses a protective MBR (1 block), a GPT header (1 block),
+    and usually a partition entry array that takes up about 32 blocks.
+  - Total: approximately 34 blocks (assuming a 512-byte block size).
+
+Recommendation: For deleting a GPT partition table, use a block size of 512 bytes
+                and overwrite at least 34 blocks to ensure the entire table is cleared.
+##########################################################################################"""
+
+
+def optimal_blocksize(name: str, sys_block_path: Path = SYS_BLOCK_PATH) -> str:
+    """64 * physical block size, or "4K" when the size cannot be read.
+
+    See https://www.heise.de/ct/hotline/Optimale-Blockgroesse-fuer-dd-2056768.html
+    """
+    size_path = sys_block_path / name / "queue" / "physical_block_size"
+    try:
+        return str(64 * int(size_path.read_text().strip()))
+    except (OSError, ValueError):
+        return "4K"
+
+
+@dataclass(frozen=True)
+class Device:
+    name: str  # e.g. "sda" or "mmcblk0"
+
+    @property
+    def path(self) -> str:
+        return f"/dev/{self.name}"
+
+    @property
+    def optimal_blocksize(self) -> str:
+        return optimal_blocksize(self.name)
+
+    def partition(self, number: int) -> str:
+        """/dev/sda -> /dev/sda1, /dev/mmcblk0 -> /dev/mmcblk0p1."""
+        if self.name[-1].isdigit():
+            return f"{self.path}p{number}"
+        return f"{self.path}{number}"
+
+
+def is_block_device(path: str) -> bool:
+    try:
+        return stat_module.S_ISBLK(Path(path).stat().st_mode)
+    except OSError:
+        return False
+
+
+def select_device() -> Device:
+    ui.info("Available devices:")
+    runner.run(["lsblk", "-o", "NAME,SIZE,TYPE,MODEL"], check=False)
+    name = ui.ask("Please type in the name of the device: /dev/")
+    device = Device(name)
+    if not name or not is_block_device(device.path):
+        raise LimError(f"{device.path} is not a valid device.")
+    ui.info(f"Device path set to: {device.path}")
+    ui.info(f"Optimal blocksize set to: {device.optimal_blocksize}")
+    return device
+
+
+def overwrite_device(device: Device) -> None:
+    """Optionally overwrite the device (or its first blocks) with zeros."""
+    print(PARTITION_TABLE_INFO)
+    answer = ui.ask(
+        f"Should {device.path} be overwritten with zeros before copying? (y/N/block count)"
+    )
+    if answer == "y":
+        ui.info("Overwriting entire device...")
+        runner.run(
+            [
+                "dd",
+                "if=/dev/zero",
+                f"of={device.path}",
+                f"bs={device.optimal_blocksize}",
+                "status=progress",
+            ],
+            sudo=True,
+            error_msg=f"Overwriting {device.path} failed.",
+        )
+        runner.sync_disks()
+    elif answer in ("", "N"):
+        ui.info("Skipping Overwriting...")
+    elif answer.isdigit():
+        ui.info(f"Overwriting {answer} blocks...")
+        runner.run(
+            [
+                "dd",
+                "if=/dev/zero",
+                f"of={device.path}",
+                f"bs={device.optimal_blocksize}",
+                f"count={answer}",
+                "status=progress",
+            ],
+            sudo=True,
+            error_msg=f"Overwriting {device.path} failed.",
+        )
+        runner.sync_disks()
+    else:
+        raise LimError("Invalid input. Block count must be a number.")
+
+
+def blkid_value(path: str, tag: str) -> str:
+    """Return a blkid tag value ("TYPE", "UUID", ...) or "" when unavailable."""
+    return runner.output(
+        ["blkid", path, "-s", tag, "-o", "value"], sudo=True, check=False
+    )
+
+
+def is_mounted(path_fragment: str) -> bool:
+    """Whether any current mount line contains the given fragment."""
+    mounts = runner.output(["mount"], check=False)
+    return any(path_fragment in line for line in mounts.splitlines())

lim/distributions.yml

@@ -0,0 +1,67 @@
+# Single point of truth for the downloadable image catalog.
+# Consumed by lim/catalog.py.
+
+# Image and LUKS --pbkdf-memory cost per Raspberry Pi version.
+arch_rpi_images:
+  "1":
+    image: ArchLinuxARM-rpi-armv7-latest.tar.gz
+    luks_memory_cost: "64000"
+  "2":
+    image: ArchLinuxARM-rpi-armv7-latest.tar.gz
+    luks_memory_cost: "128000"
+  "3b":
+    image: ArchLinuxARM-rpi-aarch64-latest.tar.gz
+    luks_memory_cost: "128000"
+  "3b+":
+    image: ArchLinuxARM-rpi-aarch64-latest.tar.gz
+    luks_memory_cost: "128000"
+  "4":
+    image: ArchLinuxARM-rpi-aarch64-latest.tar.gz
+    luks_memory_cost: "256000"
+
+manjaro_gnome_releases:
+  "20":
+    checksum: 2df3697908483550d4a473815b08c1377e6b6892
+    url: https://osdn.net/projects/manjaro-archive/storage/gnome/20.0/
+    image: manjaro-gnome-20.0-200426-linux56.iso
+  "21":
+    url: https://download.manjaro.org/gnome/21.3.7/
+    image: manjaro-gnome-21.3.7-220816-linux515.iso
+  "22":
+    url: https://download.manjaro.org/gnome/22.1.3/
+    image: manjaro-gnome-22.1.3-230529-linux61.iso
+  "24":
+    url: https://download.manjaro.org/gnome/24.2.1/
+    image: manjaro-gnome-24.2.1-241216-linux612.iso
+  "25":
+    url: https://download.manjaro.org/gnome/25.0.10/
+    image: manjaro-gnome-25.0.10-251013-linux612.iso
+  # At the moment just optimized for Raspberry Pi 4.
+  raspberrypi:
+    url: https://github.com/manjaro-arm/rpi4-images/releases/download/23.02/
+    image: Manjaro-ARM-gnome-rpi4-23.02.img.xz
+    luks_memory_cost: "256000"
+    raspberry_pi_version: "4"
+
+retropie_images:
+  "1":
+    checksum: 95a6f84453df36318830de7e8507170e
+    image: retropie-buster-4.8-rpi1_zero.img.gz
+  "2":
+    checksum: 224e64d8820fc64046ba3850f481c87e
+    image: retropie-buster-4.8-rpi2_3_zero2w.img.gz
+  "3":
+    checksum: 224e64d8820fc64046ba3850f481c87e
+    image: retropie-buster-4.8-rpi2_3_zero2w.img.gz
+  "4":
+    checksum: b5daa6e7660a99c246966f3f09b4014b
+    image: retropie-buster-4.8-rpi4_400.img.gz
+
+# Extra kernel modules the initramfs needs for early network access,
+# see https://raspberrypi.stackexchange.com/questions/67051
+mkinitcpio_modules_by_rpi:
+  "1": ""
+  "2": ""
+  "3b": smsc95xx
+  "3b+": lan78xx
+  "4": lan78xx

lim/errors.py

@@ -0,0 +1,2 @@
+class LimError(Exception):
+    """Fatal error that aborts the current lim command."""

lim/fsutil.py

@@ -0,0 +1,32 @@
+"""Small file manipulation helpers."""
+
+from pathlib import Path
+
+from lim import ui
+from lim.errors import LimError
+
+
+def replace_in_file(search: str, replace: str, path: str | Path) -> None:
+    """Replace every literal occurrence of ``search``; fail when absent."""
+    path = Path(path)
+    text = path.read_text()
+    new_text = text.replace(search, replace)
+    if new_text == text:
+        raise LimError(f"Search string '{search}' not found in {path}.")
+    path.write_text(new_text)
+
+
+def ensure_line_in_file(line: str, path: str | Path) -> bool:
+    """Append ``line`` unless already present. Returns True when appended."""
+    path = Path(path)
+    content = path.read_text() if path.exists() else ""
+    if line in content.splitlines():
+        ui.warning(f"File {path} already contains the following entry:")
+        print(line)
+        ui.info("Skipped.")
+        return False
+    with path.open("a") as handle:
+        if content and not content.endswith("\n"):
+            handle.write("\n")
+        handle.write(line + "\n")
+    return True

lim/image/backup.py

@@ -0,0 +1,32 @@
+"""Create an image backup from a memory device into a file."""
+
+from pathlib import Path
+
+from lim import device as device_module
+from lim import runner, ui
+
+
+def run_backup() -> None:
+    ui.info("Backupscript for memory devices started...")
+    print()
+    device = device_module.select_device()
+
+    working_dir = Path.cwd()
+    path = ""
+    while not path:
+        path = ui.ask(f"Please type in backup image path+name relative to {working_dir}:")
+    output_file = f"{path}.img" if path.startswith("/") else f"{working_dir}/{path}.img"
+
+    ui.info(f"Input file: {device.path}")
+    ui.info(f"Output file: {output_file}")
+    ui.ask('Please confirm by pushing "Enter". To cancel use "Ctrl + C"')
+
+    ui.info("Imagetransfer starts. This can take a while...")
+    runner.run(
+        ["dd", f"if={device.path}", f"of={output_file}", "bs=1M", "status=progress"],
+        sudo=True,
+        error_msg='"dd" failed.',
+    )
+    runner.sync_disks()
+
+    ui.success("Imagetransfer successfull.")