What a program needs to run a migration the guide's way without copying the guide (the Admin migrations screen, step 1b): - plan --answers FILE DIR writes the guide's plans from its answers: plan.json, preview-plan.json and the setup's directory, and says on stdout which files to run and which variables hold the secrets. The answers carry no secrets; a file that does is refused. The guide now writes its plans through the same code. - --stay-on-url, on import jmap, export, export-directory and import-directory, moves every session URL onto the --url origin, for a server reached at an address it doesn't advertise (its own loopback, a tunnel). The answers' target takes stayOnUrl and allowInvalidCerts. - import imap --google-key-from-env reads the service account's key from $INBUXA_MIGRATE_GOOGLE_KEY; a plan step names it as the googleKey secret. A Google source whose keyFile is empty takes the key as its secret.
7.4 KiB
inbuxa-migrate
Note
Development happens on git.coffeylabs.org/inbuxa/inbuxa-migrate; the copy on GitHub is a read-only mirror. Report issues at git.coffeylabs.org/inbuxa/inbuxa-migrate/issues, join discussions at community.coffeylabs.org, or chat on Discord.
One program that moves an account into inbuxa: its mail, calendars, contacts, identities, Sieve scripts and files.
inbuxa-migrate import imap … alice.sqlite an account into an archive
inbuxa-migrate inspect alice.sqlite what landed
inbuxa-migrate export … alice.sqlite the archive into inbuxa
inbuxa-migrate export-files alice.sqlite out the archive as plain files
inbuxa-migrate export-imap … alice.sqlite its mail into any IMAP server
inbuxa-migrate export-managesieve … alice.sqlite its filters, likewise
inbuxa-migrate export-caldav … alice.sqlite its calendars into any CalDAV server
inbuxa-migrate export-carddav … alice.sqlite its contacts into any CardDAV server
inbuxa-migrate export-directory … out a server's accounts, no secrets
inbuxa-migrate import-directory … out those accounts, set up on inbuxa
inbuxa-migrate migrate --plan plan.json work many accounts, by a plan
inbuxa-migrate guide work the same, walked through in the browser
Between the two sides sits an archive: one SQLite file holding one account.
import fills it from the old server; export writes it into the new one.
Import and export never talk to each other, only to the archive, so the old
server can be gone before the new one exists.
Both commands converge. An interrupted run picks up where it stopped, and a
later import into the same archive adds what arrived since. Every command
takes --dry-run and then only reports the plan. inspect reads an archive
and changes nothing.
The archive is also a backup. Import on a schedule, keep the file, and
restore it later with export. An archive remembers which account filled it
and refuses a different one unless told otherwise.
Export speaks JMAP only. It writes into inbuxa, or into any JMAP server that
advertises the types being written. export-imap writes the mail into any
IMAP server, export-managesieve the Sieve filters into any ManageSieve
server, export-caldav and export-carddav the calendars and contacts into
any CalDAV and CardDAV server, and export-files is the way out to everything else: it writes
the archive as a Maildir++ tree, vCard, iCalendar and Sieve files that other
servers and mail, calendar and contacts apps open, with no network and no
store format in the way. For a whole server, export-directory writes the
list of domains, accounts, groups, lists and aliases to set up again
elsewhere, without passwords, and import-directory sets them up on an
inbuxa server, with a new password for each user. migrate moves many
accounts with one plan file: the same steps for each account, several at
once, resuming where it stopped, with one report at the end. guide
walks through the same move in the browser: it asks where the mail is,
which accounts and which inbuxa server, previews, and runs the plan it
writes. The full
command reference is in docs/usage.md.
Sources
- JMAP -- any JMAP account, including an inbuxa or Stalwart server.
- IMAP -- mail only. Folders are chosen by name or by pattern.
- CalDAV, CardDAV -- calendars and events, address books and contacts.
- WebDAV -- a plain file collection, kept as a file tree.
- ManageSieve -- Sieve scripts only, with the active one recorded.
- Maildir -- a local Maildir++ tree. No network.
- Google Takeout -- the
.mbox,.icsand.vcffiles in a Takeout export, or in any directory tree laid out that way. - Exchange Server -- an on-premises mailbox, through EWS.
- Exchange Online -- through Microsoft Graph. EWS is being retired in Exchange Online: blocked from October 1, 2026 unless an administrator allows the client, and switched off on April 1, 2027. Public folders are only reachable through EWS.
Credentials
Secrets are read from the environment, or asked for at a prompt:
INBUXA_MIGRATE_PASSWORD a password for --auth-basic
INBUXA_MIGRATE_API_KEY an API key or bearer token for --auth-bearer
(INBUXA_MIGRATE_TOKEN still works)
INBUXA_MIGRATE_EWS_CLIENT_SECRET the OAuth client secret for app-only EWS
INBUXA_MIGRATE_GRAPH_TOKEN a Microsoft Graph access token
INBUXA_MIGRATE_GOOGLE_KEY a Google service account's JSON key,
for --google-key-from-env
The command line takes them too, but a secret there ends up in the shell's history and in the process list. Use the environment or the prompt.
Installing
Linux, on amd64 or arm64. Each release carries one archive per architecture
and a SHA256SUMS file:
base=https://git.coffeylabs.org/inbuxa/inbuxa-migrate/releases/latest/download
curl -fLO "$base/inbuxa-migrate-linux-amd64.tar.gz"
curl -fLO "$base/SHA256SUMS"
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf inbuxa-migrate-linux-amd64.tar.gz
./inbuxa-migrate --version
On arm64, fetch inbuxa-migrate-linux-arm64.tar.gz instead. The binary is
the whole program; put it anywhere on the path.
Building and testing
cargo build --release the binary is target/release/inbuxa-migrate
cargo test the default suite
The default suite needs no network and no Docker. Unit tests and scripted mocks stand in for JMAP, DAV, EWS and Graph servers.
The live tests are marked #[ignore]. Each boots a throwaway container --
Stalwart, Dovecot, Cyrus, Radicale, Baikal or Apache mod_dav -- so they
need a working Docker daemon. Run them one binary at a time, and always with
one test thread:
cargo test --test sync_jmap -- --ignored --test-threads=1
cargo test --test integration_dovecot -- --ignored --test-threads=1
The tests in a binary share one container and one disposable domain, so a second thread would trip over the first. docs/usage.md lists every live test binary.
License
Apache-2.0 OR MIT, at your option. The texts are in LICENSES.
Copyright (C) 2020, Stalwart Labs LLC
Copyright (C) 2026 Coffey Labs LLC
Forked from Vandelay, originally developed by Stalwart Labs, and distributed under the same Apache-2.0 OR MIT terms.