Skip to content

mt-migrate — Ubuntu 18.04 → 24.04 migration tool

mt-migrate captures a customer system running Ubuntu 18.04 (Canvus Server, Canvus Client, Showcase, Launcher, Cornerstone display configuration, and OS-level state) into an integrity-checked bundle, then applies that bundle to a freshly-installed 24.04 target.

It is a single static binary with no runtime dependencies on the customer's box. Built CGO-free, statically linked, linux/amd64.

Current release — 1.1.0

Released 2026-08-05

Restore ownership release. Files restored into a user's home directory are now handed back to that user, so Canvus, Showcase and Launcher can write their own configuration when they start. Before 1.1.0 everything under /home/<user>/ was left owned by root: the import reported success, and the applications hit permission denied later, the first time they tried to save anything. Restored ~/.ssh directories and per-user crontabs are corrected the same way — both were previously left unusable.

Also adds the mt-only profile, for restoring MT state onto a 24.04 machine that is already configured. Drop-in replacement for 1.0.3.

Download:

Quickstart

Verify, install, run. Replace /mnt/usb with wherever you want the bundle written (USB drive, mounted network folder, second internal drive).

# 1. Download + verify
curl -fLO https://apps.multitaction.com/download/s3/mt-migrate/v1.1.0/mt-migrate-1.1.0-linux-amd64
curl -fLO https://apps.multitaction.com/download/s3/mt-migrate/v1.1.0/mt-migrate-1.1.0-linux-amd64.sha256
sha256sum -c mt-migrate-1.1.0-linux-amd64.sha256

# 2. Install
chmod +x mt-migrate-1.1.0-linux-amd64
sudo mv mt-migrate-1.1.0-linux-amd64 /usr/local/bin/mt-migrate

# 3. On the 18.04 source host — capture
sudo mt-migrate --non-interactive export --dest /mnt/usb --passphrase "" --primary-user multi

# 4. Move the resulting MT_MIGRATION_* directory to the 24.04 target via the same USB/network folder

# 5. On the 24.04 target — apply
sudo mt-migrate --non-interactive import --src /mnt/usb/MT_MIGRATION_<hostname>_<timestamp>

The export step prints a pre-flight report showing every module's capture status. A green report with no [FAILED] or [UNRECOGNIZED] layers means the bundle is ready to ship.

For per-flag detail run mt-migrate export --help or mt-migrate import --help.

Restoring onto a machine that is already configured

If the 24.04 box is already named, networked and set up the way the customer wants it, use the mt-only profile. It restores the MT applications, licenses, display layout and touch configuration, and leaves the target's hostname, hosts file, DNS resolver, SSH host keys, timezone and cron jobs alone.

sudo mt-migrate import --src /mnt/usb/MT_MIGRATION_<hostname>_<timestamp> --profile mt-only --dry-run

Read the layer report, then run it again without --dry-run.

The default safe-defaults profile applies the old machine's system configuration too. That is correct when the 24.04 box is a blank replacement for the old one, and wrong when it has a name, network or SSH identity that people already rely on — mt-migrate keeps no copy of what it overwrites, so there is nothing to roll back to.

If the target session is Wayland, xorg.conf is skipped. MT display walls normally need it, so add --include=cornerstone.xorg. Have console access when you do: an xorg.conf from the old machine names the old machine's graphics driver, and a mismatch can leave you at a black screen.

What mt-migrate captures

Module What it covers
system.network netplan / interfaces files, hostname, hosts, ufw rules
system.locale timezone, keyboard, locale
system.scheduling crontabs (system + per-user)
system.identity SSH host keys, sshd_config, ca-additions, ssl-private
canvus.server /var/lib/mt-canvus-server/MultiTaction/{DataModel,backups,...} ; reassembled at /canvus-data/ on the 24.04 container deployment
canvus.client per-user ~/MultiTaction/canvus/
launcher /etc/MultiTaction/launcher/ + per-user ~/MultiTaction/launcher/
showcase production_users.yaml, assets, backups, pg_dump -F c of mt-showcase and mt-showcase-reporting databases
licenses every documented .cslicense location on Linux: /var/lib/mt-canvus-server/MultiTaction/Licenses/, /opt/mt-showcase/licenses/, per-user ~/MultiTaction/Licenses/, per-user ~/.config/MultiTaction/Licenses/
cornerstone xorg.conf, screen.xml, config.txt, per-user ~/.MultiTouch/ (display calibration)

The Showcase database translation step (1.x Postgres → 26.4 SQLite) ships as the showcase-translate subcommand. Run it on the target after installing mt-showcase; it converts the captured dump and writes the database the 26.4 server reads on first start.

What mt-migrate does not do

mt-migrate moves your data. It does not upgrade it.

The schema jump from Canvus 3.x and Showcase 1.14 up to 26.4 is performed by the applications themselves, the first time you start them on the new machine. Canvus Server applies its own database migrations on startup, Showcase evolves its database on first launch, and the Launcher package converts its config format during install. mt-migrate has already finished by then.

A successful import is not a successful upgrade

mt-migrate import reports success as soon as the files are staged. Whether your canvases, presentations, themes and schedules survive the version jump is determined later, when each application starts. Open every application and verify your content before returning the system to service.

The 3.x / 1.14 → 26.4 upgrade path has been validated against test data, but not yet against a production customer dataset. If you are migrating a system carrying content you cannot afford to lose, take an independent backup of the source machine before you begin and keep it until you have verified the target.

Source

This tool is developed in swrd/ub18.04-to-ub24.04-migration. Release notes and source for every release are at the project's GitLab releases page.

For the design specification — including the bundle layout, the pre-flight contract, and the per-module capture/apply semantics — see dev/superpowers/specs/2026-05-01-migration-tool-design.md in the project repository.