Revise README for ubuntu-to-mint-convert-v3
Updated project name and expanded documentation for conversion script.
This commit is contained in:
LINUXexpert.org
@@ -1,2 +1,245 @@
|
||||
# ubuntu2mint
|
||||
Scripted conversion of Ubuntu to Mint
|
||||
# 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, 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 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”**)
|
||||
- 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
|
||||
|
||||
|
||||
## 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).
|
||||
|
||||
## 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`
|
||||
- Recommended:
|
||||
- **Timeshift** snapshot configured
|
||||
- Full-disk backup or VM snapshot
|
||||
|
||||
## Quick start
|
||||
|
||||
### 1) Clone and run doctor checks
|
||||
|
||||
```bash
|
||||
git clone https://github.com/<your-username>/ubuntu-to-mint-convert-v3.git
|
||||
cd ubuntu-to-mint-convert-v3
|
||||
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/`.
|
||||
|
||||
```bash
|
||||
sudo bash ubuntu-to-mint-convert-v3.sh plan --edition cinnamon
|
||||
```
|
||||
|
||||
> Note: plan mode expects the Mint repo keyring to exist. If you haven’t run `convert` before, install the key or run convert on a test machine first.
|
||||
|
||||
### 3) Run conversion
|
||||
|
||||
```bash
|
||||
sudo bash ubuntu-to-mint-convert-v3.sh convert --i-accept-the-risk --edition cinnamon
|
||||
```
|
||||
|
||||
You can skip interactive confirmation with `--yes`:
|
||||
|
||||
```bash
|
||||
sudo bash ubuntu-to-mint-convert-v3.sh convert --i-accept-the-risk --edition cinnamon --yes
|
||||
```
|
||||
|
||||
### 4) Reboot and validate
|
||||
|
||||
After conversion:
|
||||
|
||||
1. Reboot
|
||||
2. Select your chosen desktop session at login
|
||||
3. Validate:
|
||||
|
||||
* VPN connectivity
|
||||
* EDR/MDM agents + compliance posture
|
||||
* 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 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
|
||||
|
||||
* `--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`)
|
||||
|
||||
* `--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).
|
||||
|
||||
* `--with-recommends`
|
||||
Allow installation of recommended packages (default: off for safety).
|
||||
|
||||
* `--yes`
|
||||
Skip interactive confirmation prompt.
|
||||
|
||||
|
||||
## 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
|
||||
* 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
|
||||
|
||||
|
||||
## 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
|
||||
* snap/flatpak lists (if installed)
|
||||
* simulation output
|
||||
|
||||
|
||||
## Rollback
|
||||
|
||||
Rollback restores `/etc/apt` and any disabled sources from the backup:
|
||||
|
||||
```bash
|
||||
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 reachable
|
||||
* corporate proxy settings
|
||||
* If needed:
|
||||
|
||||
* rollback using the backup directory
|
||||
|
||||
### Desktop won’t start / login loop
|
||||
|
||||
* Boot to a TTY (`Ctrl+Alt+F3`)
|
||||
* Inspect:
|
||||
|
||||
* `/var/log/syslog`
|
||||
* `journalctl -b -p err`
|
||||
* Consider switching display manager or reinstalling desktop meta packages:
|
||||
|
||||
* `sudo apt-get install --reinstall lightdm slick-greeter`
|
||||
|
||||
### 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.
|
||||
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user