ubuntu2mint/README.md

ubuntu-to-mint-convert-v3

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, 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.3)

• 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 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

• It does not replace your OS identity with Mint in a fully supported way.
• 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

• Ubuntu 24.04 (noble) or 22.04 (jammy)
• Root access (sudo)
• Working APT and dpkg state (the script attempts basic remediation)
• 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

git clone https://github.com/LINUXexpert-org/ubuntu2mint.git
cd ubuntu2mint
sudo bash ubuntu-to-mint-convert-v3.sh doctor

2) (Optional) Run plan mode (dry-run)

Plan mode simulates the APT changes and writes a log under /var/log/ubuntu-to-mint/.

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 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

sudo bash ubuntu-to-mint-convert-v3.sh convert --i-accept-the-risk --edition cinnamon

You can skip the secondary confirmation prompt with --yes:

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. Login via LightDM (slyck-greeter) and confirm your default session loads

3. Validate:

   • VPN connectivity (GlobalProtect, etc.)
   • EDR/MDM agents + compliance posture (CrowdStrike Falcon, etc.)
   • Corporate certificates / SSO
   • NetworkManager
   • Printers
   • Smartcards / YubiKey
   • Cameras/audio

Usage

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

Core

• --edition cinnamon|mate|xfce Desktop edition meta-package to install (default: cinnamon).

• --target <mint_codename> Override the Mint target codename. Allowed targets depend on your Ubuntu base:

  • Ubuntu noble: zena, zara, xia, wilma
  • Ubuntu jammy: virginia, victoria, vera, vanessa

• --mint-mirror <url> Override Mint mirror base URL (default: http://packages.linuxmint.com).

Safety / APT behavior

• --keep-ppas Do not disable third-party APT sources (not recommended).

• --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 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)

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 (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

Logs

• Main log file:

  • /var/log/ubuntu-to-mint/ubuntu-to-mint-YYYYMMDD-HHMMSS.log

• Plan output logs:

  • /var/log/ubuntu-to-mint/plan-YYYYMMDD-HHMMSS.txt

Backup directory

During convert, a backup directory is created, for example:

• /root/ubuntu-to-mint-backup-YYYYMMDD-HHMMSS/

Contains:

• /etc/apt backup
• package inventories (apt-manual, holds, dpkg list)
• enabled systemd services list
• simulation output
• (if present) saved list of held packages (when --allow-unhold is used)
• (if used) disabled third-party sources captured for restore

Rollback

Rollback restores /etc/apt and any disabled sources from the backup:

sudo bash ubuntu-to-mint-convert-v3.sh rollback /root/ubuntu-to-mint-backup-YYYYMMDD-HHMMSS
sudo apt-get update
sudo apt-get -f install

Rollback restores APT configuration but may not remove packages installed during conversion. 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)

2. Ensure Timeshift is configured and can restore

3. Run:

   • doctor
   • plan and review logs

4. Only then run convert

5. Reboot and validate corporate tooling

Troubleshooting

APT update fails after conversion

• Check:

  • /etc/apt/sources.list.d/official-package-repositories.list
  • Mint mirror reachability
  • corporate proxy settings

• If needed:

  • rollback using the backup directory

Desktop won’t start / login loop

• Boot to a TTY (Ctrl+Alt+F3)

• Inspect:

  • journalctl -b -p err

• Consider reinstalling LightDM and the greeter:

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:

sudo bash ubuntu-to-mint-convert-v3.sh convert --i-accept-the-risk --recreate-keyring

Corporate VPN/EDR breaks

• Reinstall using corporate-provided packages
• Re-enroll if required
• Validate kernel modules, certificate stores, and PAM stack

Security & compliance considerations

If this is a corporate-managed device:

• Get explicit approval before modifying base OS repositories
• Confirm your organization’s standard OS images and compliance requirements
• Expect that security tooling may detect drift and require remediation

License

Copyright (C) 2026 LINUXexpert.org

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.