diff --git a/README.md b/README.md index 15df7b9..efff68d 100644 --- a/README.md +++ b/README.md @@ -2,22 +2,40 @@ High-risk, best-effort **in-place conversion** script that keeps **Ubuntu as the base OS** while adding **Linux Mint repositories + Mint desktop/tooling** to approximate a Linux Mint system without a full reinstall. -This project is intended for experienced Linux admins who understand APT, repo pinning, and rollback strategies. +This project is intended for experienced Linux admins who understand APT, repo pinning, display managers, and rollback strategies. > ⚠️ **Warning (Read This First)** > There is **no guaranteed safe** way to convert Ubuntu to Linux Mint in-place and preserve *all* corporate software/agents. > EDR/MDM/VPN/compliance tooling may break and require re-enrollment. Use this only if you accept that risk. + + +## What changed in the latest script (v4.2) + +- **Convert-only “unsupported migration” disclaimer gate** (requires typing: `I UNDERSTAND THIS IS UNSUPPORTED`) +- Defaults to **LightDM + slick-greeter** and explicitly sets the **default desktop session** +- **X11 is the default session preference** (safer for conversions/corporate tooling) +- Added `--prefer-wayland` (best-effort only; may fall back to X11 with a warning) +- Improved Mint repo key handling: + - `--overwrite-keyring` / `--recreate-keyring` + - automatic detection/repair if the keyring exists but doesn’t contain the expected key + - HKPS → HKP:80 → HTTPS fallback, with **atomic keyring writes** +- Improved plan mode: uses a temporary APT environment (no changes to system APT files) + + + ## What this does - Detects supported Ubuntu bases: - - **Ubuntu 24.04 (noble)** → targets **Linux Mint 22.x** (default **22.3 “zena”**) - - **Ubuntu 22.04 (jammy)** → targets **Linux Mint 21.x** (default **21.3 “virginia”**) + - **Ubuntu 24.04 (noble)** → targets **Linux Mint 22.x** (default target: **zena**) + - **Ubuntu 22.04 (jammy)** → targets **Linux Mint 21.x** (default target: **virginia**) - Adds the Linux Mint package repository (`packages.linuxmint.com`) - Keeps Ubuntu repos for the underlying base system - Installs Mint meta-packages (desktop + tooling) - Applies conservative APT pinning so Ubuntu remains the default for overlapping packages - Includes safety checks, dry-run planning, and rollback support +- Sets **display manager + greeter + default session** based on `--edition` + ## What this does *not* do @@ -26,6 +44,9 @@ This project is intended for experienced Linux admins who understand APT, repo p - It does **not** guarantee your machine remains compliant in managed enterprise environments. - It does **not** guarantee perfect package resolution—APT may still want to remove packages. - Rollback restores `/etc/apt`, but may not remove packages installed during conversion (use snapshots/Timeshift for full reversion). +- `--prefer-wayland` is **best-effort** and may fall back to X11 depending on what sessions are available and LightDM compatibility. + + ## Requirements @@ -35,10 +56,13 @@ This project is intended for experienced Linux admins who understand APT, repo p - Internet access to: - Ubuntu mirrors (or your corporate mirror) - `packages.linuxmint.com` + - key retrieval endpoints (HKPS/HKP/HTTPS fallbacks) - Recommended: - **Timeshift** snapshot configured - Full-disk backup or VM snapshot + + ## Quick start ### 1) Clone and run doctor checks @@ -60,7 +84,7 @@ sudo bash ubuntu-to-mint-convert-v3.sh plan --edition cinnamon Plan mode simulates APT changes using a **temporary APT environment** (it does not modify your system’s APT sources). It will fetch the Linux Mint repository signing key into a **temporary keyring** for the simulation. -> Note: If `gnupg`/`dirmngr` are missing, plan mode may install them so it can import and dearmor the Mint signing key. +> Note: If `curl`/`gnupg`/`dirmngr` are missing, plan mode may require installing prerequisites if you run with `--auto-fix`. > No repository files on your system are changed by plan mode. ### 3) Run conversion @@ -69,38 +93,46 @@ It will fetch the Linux Mint repository signing key into a **temporary keyring** sudo bash ubuntu-to-mint-convert-v3.sh convert --i-accept-the-risk --edition cinnamon ``` -You can skip interactive confirmation with `--yes`: +You can skip the secondary confirmation prompt with `--yes`: ```bash sudo bash ubuntu-to-mint-convert-v3.sh convert --i-accept-the-risk --edition cinnamon --yes ``` +> The **big red unsupported disclaimer** is still required during `convert` even if `--yes` is set. + ### 4) Reboot and validate After conversion: 1. Reboot -2. Select your chosen desktop session at login +2. Login via LightDM (slyck-greeter) and confirm your default session loads 3. Validate: - * VPN connectivity - * EDR/MDM agents + compliance posture + * VPN connectivity (GlobalProtect, etc.) + * EDR/MDM agents + compliance posture (CrowdStrike Falcon, etc.) * Corporate certificates / SSO * NetworkManager * Printers * Smartcards / YubiKey * Cameras/audio + + ## Usage ```text -sudo bash ubuntu-to-mint-convert-v3.sh doctor +sudo bash ubuntu-to-mint-convert-v3.sh doctor [--auto-fix] sudo bash ubuntu-to-mint-convert-v3.sh plan [options] sudo bash ubuntu-to-mint-convert-v3.sh convert --i-accept-the-risk [options] sudo bash ubuntu-to-mint-convert-v3.sh rollback /root/ubuntu-to-mint-backup-YYYYMMDD-HHMMSS ``` -### Options + + +## Options + +### Core * `--edition cinnamon|mate|xfce` Desktop edition meta-package to install (default: `cinnamon`). @@ -112,19 +144,49 @@ sudo bash ubuntu-to-mint-convert-v3.sh rollback /root/ubuntu-to-mint-backup-YYYY * Ubuntu `jammy`: `virginia`, `victoria`, `vera`, `vanessa` * `--mint-mirror ` - Override Mint mirror base URL (default: `http://packages.linuxmint.com`) + Override Mint mirror base URL (default: `https://packages.linuxmint.com`). + +### Safety / APT behavior * `--keep-ppas` Do not disable third-party APT sources (not recommended). -* `--preserve-snap` - Keep Snap working even if Mint preferences attempt to disable it (default: enabled). +* `--allow-unhold` + Temporarily unhold held packages during conversion (risky; holds are re-applied later). * `--with-recommends` Allow installation of recommended packages (default: off for safety). +* `--auto-fix` + For `doctor`/`plan`: allow basic dpkg/apt remediation and install missing tool prerequisites. + * `--yes` - Skip interactive confirmation prompt. + Skip the secondary interactive confirmation prompt inside convert (does **not** bypass the main disclaimer gate). + +### Snap handling + +* `--preserve-snap` (default) + Keep Snap working even if Mint preferences attempt to disable it. + +* `--no-preserve-snap` + Do not try to preserve Snap behavior. + +### Keyring handling + +* `--overwrite-keyring` + Overwrite the Mint repo keyring if it exists. + +* `--recreate-keyring` + Back up the existing keyring and recreate it from scratch. + +### Wayland / X11 behavior + +* (default) **Prefers X11 session** + Safer for conversions and enterprise desktop tooling. + +* `--prefer-wayland` + Best-effort attempt to prefer Wayland if it is **LightDM-compatible** (otherwise warns and falls back to X11). + ## Safety model (important) @@ -134,12 +196,14 @@ The script includes guardrails to reduce “brick your system” outcomes: * Refuses to run unless on supported Ubuntu bases * Detects and blocks active APT/dpkg locks * Attempts to repair basic dpkg/apt broken states -* Disables PPAs by default during conversion +* Disables PPAs by default during conversion (while attempting to preserve vendor repos for Falcon/GlobalProtect when identifiable) * Runs an APT simulation and aborts if: * APT wants to remove critical packages (e.g., `sudo`, `systemd`, `network-manager`, kernel packages, `snapd`) * too many removals are detected * Writes detailed logs and creates a backup folder for rollback +* Validates post-conversion basics (LightDM default, session file, NetworkManager, apt health, and best-effort checks for Falcon/GlobalProtect presence) + ## Logs and backups @@ -164,8 +228,10 @@ Contains: * `/etc/apt` backup * package inventories (`apt-manual`, holds, dpkg list) * enabled systemd services list -* snap/flatpak lists (if installed) * simulation output +* (if present) saved list of held packages (when `--allow-unhold` is used) +* (if used) disabled third-party sources captured for restore + ## Rollback @@ -182,6 +248,7 @@ sudo apt-get -f install > For full restoration use Timeshift / snapshot / backup. + ## Recommended workflow (for best odds) 1. Test in a VM first (same Ubuntu version and similar package set) @@ -194,6 +261,7 @@ sudo apt-get -f install 5. Reboot and validate corporate tooling + ## Troubleshooting ### APT update fails after conversion @@ -201,7 +269,7 @@ sudo apt-get -f install * Check: * `/etc/apt/sources.list.d/official-package-repositories.list` - * Mint mirror reachable + * Mint mirror reachability * corporate proxy settings * If needed: @@ -212,11 +280,21 @@ sudo apt-get -f install * Boot to a TTY (`Ctrl+Alt+F3`) * Inspect: - * `/var/log/syslog` * `journalctl -b -p err` -* Consider switching display manager or reinstalling desktop meta packages: +* Consider reinstalling LightDM and the greeter: - * `sudo apt-get install --reinstall lightdm slick-greeter` +```bash +sudo apt-get install --reinstall lightdm slick-greeter +``` + +### Keyserver blocked / key import fails + +* The script attempts HKPS → HKP:80 → HTTPS fallback. +* If a keyring already exists and is broken, try: + +```bash +sudo bash ubuntu-to-mint-convert-v3.sh convert --i-accept-the-risk --recreate-keyring +``` ### Corporate VPN/EDR breaks @@ -225,6 +303,7 @@ sudo apt-get -f install * Validate kernel modules, certificate stores, and PAM stack + ## Security & compliance considerations If this is a corporate-managed device: @@ -234,6 +313,7 @@ If this is a corporate-managed device: * Expect that security tooling may detect drift and require remediation + ## License Copyright (C) 2026 LINUXexpert.org @@ -242,8 +322,7 @@ This project is licensed under the **GNU General Public License v3.0**. See the `LICENSE` file or the header in `ubuntu-to-mint-convert-v3.sh`. + ## Disclaimer This project is provided as-is. You assume all risk for system instability, data loss, or compliance impact. Always have a tested restore path before running. - -```