jcoffey-dev
4568f9abbf
Found by running preflight against a real Stalwart 0.15.5 in a VM. Two defects, the second worse than the first. 1. AccountSnapshot could not read the version this tool migrates FROM. 0.15.5 advertises no urn:stalwart:jmap capability and POST /api returns 404 - the JMAP management API and x:Account are 0.16 features. 0.15.x exposes a REST API at GET /api/principal instead. So preflight's account-snapshot check warned and moved on, and every run against a real source instance had no "before" data at all. AccountSnapshot now dispatches on the capability the session document advertises - a positive signal, not an inference from a failed call - and internal/stalwartapi/principal.go implements the 0.15.x REST path, including its 1-based page/limit pagination so an install larger than one page isn't silently truncated. 2. With no "before" counts, the content-integrity comparison iterated an empty map, checked nothing, and reported "all message counts match". That is the strongest claim this tool makes - ARCHITECTURE 4.7 calls it the actual no-data-loss guarantee - made vacuously, and it would have passed on a migration that lost every message. The comparison now derives its account set from whatever the source could report, verifies every account and domain survived either way, and carries MessageCountsCompared so the report says plainly "MESSAGE COUNTS NOT COMPARED ... no-data-loss is NOT verified here" rather than implying otherwise. What can and cannot be checked across the 0.15/0.16 boundary, now that a real server has answered: 0.15.x has no per-mailbox message count at any endpoint, and the impersonation login 0.16 offers returns 401 there, so before/after message counts are impossible for the boundary migration this tool exists for. Both versions do report per-account used quota (usedQuota in 0.15's REST list, usedDiskQuota on 0.16's x:Account), so that is captured on both sides. It is recorded and reported, not asserted on: 4.5 notes the 0.16 migration resets quotas to zero pending recalculation, so comparing those bytes across the boundary would be a false alarm generator. Test servers across preflight, validate and stalwartapi now advertise urn:stalwart:jmap, since they stand in for 0.16 instances and that capability is what says so. Verified end to end against the smoke VM: all nine preflight checks pass, and the checkpoint records 2 accounts, 1 domain and per-account used quota where it previously recorded nothing.
stalwart-migrator
In-place upgrade tool for Stalwart Mail Server, 0.15.5 → latest: no data loss, a checkpoint at every step so an interrupted run resumes instead of restarting, and automated validation that the server still works afterwards.
Recovery from a failed migration is your own snapshot or backup — this tool does not undo a migration. See Recovery is your job before using it on anything you care about.
Go, standard library only — no external dependencies.
Status
Partially implemented. Roughly 8,800 lines of tested code. Every phase
except staging now exists as a package, including cutover, but nothing wires
them into a production run yet, so run still refuses.
| Command | State |
|---|---|
stalwart-migrate preflight |
Works — read-only checks and a migration plan |
stalwart-migrate run --dry-run |
Works — preflight, real backup, sandboxed trial conversion |
stalwart-migrate run |
Refuses on purpose — see below |
stalwart-migrate status <id> |
Works |
stalwart-migrate report <id> |
Not implemented |
run without --dry-run deliberately refuses to proceed. Cutover
(ARCHITECTURE.md §4.5) is implemented and tested, but nothing calls it: the
staging phase (§4.3) and the production pipeline that would run preflight →
backup → stage → recovery-mode → cutover → validate against real paths don't
exist yet. run stops rather than going partway. That refusal is the correct
behaviour today, not a bug.
Package state:
| Package | Lines | Tests |
|---|---|---|
internal/backup |
1806 | yes |
internal/preflight |
1329 | yes |
internal/stalwartapi |
1276 | yes |
internal/cutover |
1186 | yes |
internal/validate |
792 | yes |
internal/recovery |
702 | yes |
internal/checkpoint |
556 | yes |
internal/service |
467 | yes |
internal/plan |
195 | yes |
internal/config |
stub | — |
Why not a shell script
Stalwart's 0.15 → 0.16 boundary is not a drop-in binary swap: settings move, and the data directory has to be migrated rather than merely copied. The failure mode that matters is a half-migrated mail store with no way back — which is why backup verification and checkpointing are the design centre rather than conveniences bolted on afterwards — and why the tool refuses to cut over until you confirm you have a way back.
ARCHITECTURE.md covers this in full: §1 on why a thin
wrapper is insufficient, §4 on the migration phases, §5 on the checkpoint
state machine, §6 on the CLI surface, and §8 on what is still open.
Build and test
go build ./...
go test ./...
Requires Go 1.26 or newer.
Trying it safely
preflight is the sensible starting point — its checks against the Stalwart
installation are read-only:
sudo go run ./cmd/stalwart-migrate preflight
It still needs write access, because it records the run as a checkpoint before doing anything else:
create run: checkpoint: create run directory:
mkdir /var/lib/stalwart-migrator: permission denied
That path is checkpoint.DefaultBaseDir, a compile-time constant with no
flag or environment override — so preflight needs either root or a
pre-created writable /var/lib/stalwart-migrator. (run takes --work-dir
for its scratch space, but that is a different directory and does not move
the checkpoint store.)
run --dry-run performs a real backup, which touches the live data
directory — read the caveat the command prints before using it on anything
you care about. Where the plan crosses the 0.15/0.16 boundary it clones that
verified backup into a disposable sandbox and converts the copy, leaving the
original untouched.
Recovery is your job
This tool does not undo a migration. There is no rollback command.
Recovery from a failed migration is your own snapshot or backup, taken by
whatever method you already trust and know how to restore — a ZFS, LVM or
btrfs snapshot, a VM or volume snapshot, or a restorable backup. Choosing
that method, taking it, and verifying you can actually restore from it is
out of scope for this tool: it does not take one, does not check that one
exists, and cannot restore from one.
Cutover refuses to start until you confirm a recovery point exists. That confirmation is an acknowledgement, not a check — nothing here can verify your snapshot. Its only purpose is that nobody migrates a production mail server having never been asked the question.
Take the snapshot with the service stopped if you want a clean one. A snapshot of a running Stalwart is crash-consistent rather than clean; RocksDB will usually recover from its WAL, but "usually" is doing real work in that sentence.
Restoring from a snapshot loses mail delivered since
Reverting to any pre-migration recovery point discards mail delivered between taking it and restoring it. This is inherent to restoring a point in time and this tool cannot solve it — plan your migration window with that in mind, and consider holding inbound mail at a secondary MX for the duration if the gap matters to you.
What the tool does to make a manual restore easier
- The old binary is preserved, never deleted, next to the new one as
<binary>.v<old-version>— so putting things back doesn't depend on re-downloading a specific old release under pressure. - The original service definition is preserved as
<unit>.pre-<run-id>before cutover rewrites it, so you aren't reconstructing a unit file from memory. - The settings and principals dumps taken during backup stay on disk.
- Every artifact path and checksum is in the checkpoint, and
stalwart-migrate status <run-id>prints exactly which steps completed and which failed — which is the first thing you want when deciding what to restore.
None of this is a substitute for the snapshot. It's what makes the twenty minutes after restoring one less unpleasant.
Why it works this way
An earlier version of this tool implemented rollback itself: it restored the filesystem backup, verified every restored file against a manifest, replayed SQL dumps, reinstalled the old binary, and re-validated the result. It was tested and it looked good. It was removed, because restoring bytes correctly is not the hard part — it copied contents and permissions but not ownership, so run as root it would have produced a byte-perfect, checksum-verified, root-owned data directory that Stalwart, running as its own user, could not open, and it would have reported success. A filesystem snapshot has no such failure mode, because it never lost the metadata to begin with. ARCHITECTURE.md §4.8 records the full reasoning.
License
Copyright (C) 2026 LINUXexpert-org
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.
The full text is in LICENSE. No third-party code is vendored —
this tool is standard library only, and the migrate_v016.py it downloads
at runtime is Stalwart's own script, fetched rather than redistributed.