coffey-labs/ubuntu2mint
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Enhance README with new features and clarifications

Browse Source 
Updated README to include additional details about the conversion script, including new features, requirements, and usage instructions.
This commit is contained in:
LINUXexpert.org
2026-01-23 11:26:36 -07:00
committed by GitHub
parent abd5d74cb1
commit 695996203a
1 changed files with 101 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+101 -22
View File
@@ -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.
```