Enhance README with new features and clarifications

Updated README to include additional details about the conversion script, including new features, requirements, and usage instructions.
2026-01-23 11:26:36 -07:00
parent abd5d74cb1
commit 695996203a
1 changed files with 101 additions and 22 deletions
@@ -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 <url>`
-  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.
-
-```