# Using inbuxa-migrate The full command reference. The [README](../README.md) says what the tool is and how to install it. ## Commands and global flags ``` inbuxa-migrate [args...] ``` Every command takes a few global flags -- verbosity, worker pool size, retry policy, TLS handling -- besides its own. The ones that matter most: | Flag | Purpose | | --- | --- | | `-j, --threads ` | Worker pool size (default: logical CPUs). | | `--dry-run` | Compute the full plan; perform no writes. | | `-v`, `-vv`, `-vvv` | Increase log verbosity. | | `-q, --quiet` | Warnings and errors only. | | `--max-retries ` | Max retries per request on transient failures (default 5). | | `--allow-invalid-certs` | Accept a self-signed or otherwise invalid certificate from the server named by `--url` (see below). | ### Invalid certificates `--allow-invalid-certs` is for a server with a self-signed certificate, and it applies to that server only: the host in `--url`, whether that is the source of an import or the target of an export. For an Exchange import with no `--url`, it covers the mailbox's own domain and the hosts under it, which is where on-premises Autodiscover looks, and then only the EWS endpoint Autodiscover finds. Every other host is verified as usual, including a host the server redirects to or names for its API, uploads or downloads. ### Staying on the address given A JMAP server's session names the addresses for its API, uploads and downloads, and the tool uses them, warning when they're on another host than `--url`. `--stay-on-url` sends every request to the `--url` host instead, keeping each path. It's for a server reached at an address it doesn't advertise: its own loopback, an SSH tunnel, a node behind a load balancer. `import jmap`, `export`, `export-directory` and `import-directory` take it. The Microsoft and Google sign-in and cloud endpoints are always verified, with or without the flag: a certificate that fails there is an attack or a broken network, never a server to trust. Connections time out rather than wait forever: 30 seconds to connect, 5 minutes for the server's first byte, and 30 minutes to read a whole response. A timed-out request is retried like any other transient failure. Secrets come from the `INBUXA_MIGRATE_*` environment variables or a prompt; see [Credentials](../README.md#credentials). The command line takes them too, but should not be given them. ## Import ``` inbuxa-migrate import [source-args...] ``` Reads a source account into the SQLite `ARCHIVE`, creating it if it is absent. An archive remembers which account filled it; every importer takes `--allow-source-change` to fill it from a different one anyway. The DAV importers (`caldav`, `carddav`, `webdav`) also take `--replace-source`, which first removes the other sources of the same kind, and what came from them, so a share that moved leaves one tree in the archive, not two. ### JMAP ``` inbuxa-migrate import jmap \ --url \ (--auth-basic [--auth-password ] | --auth-bearer [TOKEN]) \ (--account-id | --account-name ) \ [--objects ] \ ``` Imports one JMAP account, from inbuxa, Stalwart or any other JMAP server. `--objects` accepts a comma-separated list of object tokens (`mailbox,email,calendar,calendarevent,addressbook,contactcard,identity,sievescript,participantidentity,filenode`). The default is everything the server advertises. The out-of-office reply, the server's `VacationResponse`, comes with `sievescript`. Files are read in either shape servers spell them: `nodeType` and `type`, as inbuxa and other servers on the 0.16 line do, or `@type` and `mediaType`, as draft-ietf-jmap-filenode-18 servers such as Stalwart 1.0 do. ### IMAP ``` inbuxa-migrate import imap \ --url imap(s)://host[:port] \ (--auth-basic [--auth-password ] | --auth-bearer [TOKEN] --auth-user \ | --google-key --auth-user ) \ [--include ...] [--exclude ...] [--exclude-special ...] \ [--folder ...] [--subscribed-only] [--noautomap] \ [--include-deleted] [--allow-cleartext] [--compress] \ [--fetch-batch ] [--fetch-batch-mib ] [--imap-connections <1..8>] \ ``` Imports mail, and only mail, from any IMAP server. Folders are chosen with `--include` and `--exclude` patterns, or by exact name with `--folder`, but not both. `--exclude-special` drops folders by SPECIAL-USE role. Messages are fetched in chunks of at most `--fetch-batch` messages and `--fetch-batch-mib` MiB (32 by default), so a folder of large attachments is fetched a little at a time, like any other. A single message larger than the cap is fetched on its own. Each chunk is written to the archive as it arrives: an interrupted import keeps what it fetched, and the next run picks up from there. A message that can't be imported is reported with its folder and UID, and the rest of the folder carries on. **Gmail, a whole Google Workspace domain.** With `--google-key` the tool signs in as a Workspace service account acting for the user `--auth-user` names, so no one's password is needed. In a plan that is `--url imaps://imap.gmail.com --google-key key.json --auth-user {email}`. `--google-key-from-env` reads the key's JSON from `$INBUXA_MIGRATE_GOOGLE_KEY` instead of a file; in a plan, the step names the variable that holds it as `"secrets": {"googleKey": "..."}`. - In Google Cloud, create a service account and a JSON key for it. - In the Workspace Admin console, under domain-wide delegation, allow the service account's client id the scope `https://mail.google.com/`. IMAP has to be allowed for the users, in the Admin console's Gmail settings. - The key file holds the account's private key and reaches every mailbox in the domain: keep it readable by you alone, and delete the key in the Cloud console once the move is done. Each connection signs in with a token for that user, and takes a new one when the last is close to running out. ### CalDAV ``` inbuxa-migrate import caldav \ --url \ (--auth-basic [--auth-password ] | --auth-bearer [TOKEN]) \ [--allow-cleartext] [--dav-connections <1..8>] [--multiget-batch ] \ ``` Discovers the user's CalDAV principal (or accepts a URL pointing straight at a calendar-home or calendar), then imports calendars and events. A recurring event comes in with its changed occurrences. Someone invited to single occurrences of a series, without the series itself, has each of those occurrences as its own event, and `export`, `export-caldav` and `export-files` write them back the same way. ### CardDAV ``` inbuxa-migrate import carddav \ --url \ (--auth-basic [--auth-password ] | --auth-bearer [TOKEN]) \ [--allow-cleartext] [--dav-connections <1..8>] [--multiget-batch ] \ ``` Same shape as `caldav`, but for address books and contacts. A card the server keeps in two address books, by the same UID, is one card in both. If it leaves one book, or that book is deleted, it stays in the other; if the copies differ, the one read last is kept. ### WebDAV ``` inbuxa-migrate import webdav \ --url \ (--auth-basic [--auth-password ] | --auth-bearer [TOKEN]) \ [--allow-cleartext] [--dav-connections <1..8>] [--multiget-batch ] \ ``` Imports a plain WebDAV file collection as a JMAP `FileNode` tree. ### ManageSieve ``` inbuxa-migrate import managesieve \ --url sieve(s)://host[:port] \ (--auth-basic [--auth-password ] | --auth-bearer [TOKEN] --auth-user ) \ [--allow-cleartext] \ ``` Imports Sieve scripts only. Each script is stored once by content, and the active one is recorded. ### Maildir ``` inbuxa-migrate import maildir \ [--include ...] [--exclude ...] [--folder ...] \ [--noautomap] [--include-deleted] ``` Reads a local Maildir++ tree: a directory with `cur/`, `new/` and `tmp/`. No network. Folders are chosen as for IMAP. ### Google Takeout ``` inbuxa-migrate import takeout [--noautomap] ``` Finds every `.mbox`, `.ics` and `.vcf` file under a directory and imports it. It is shaped for Google Takeout but reads any such tree. `--noautomap` stops it giving Gmail's system labels their mailbox roles. ### An account export ``` inbuxa-migrate import files ``` Reads an account export back: the directory `export-files` writes, laid out as specifies, from this tool or any other that writes the layout. No network. Where `import maildir` and `import takeout` read the open formats on their own, this also reads the manifest, so what those formats can't hold comes back too: - every folder's real name, its place in the tree, its role and whether it was subscribed, in place of the names Maildir++ could give it on disk; - which address book and calendar were the default, and each calendar's description, color and time zone; - which Sieve script was active; - the files' media types and links; - the identities with their reply-to, bcc and signatures, and the calendar identities. A message kept in several folders is written to each folder's directory; copies with the same content come back as one message in all of those folders. The same goes for a card in two address books and an event in two calendars. A message's arrival time is its file's modification time. The manifest's paths are data, so each is checked to stay inside its part of the export, and nothing that is a symbolic link is followed: a link in the tree is skipped with a warning, and the links an account had are made from the manifest as archive entries. A directory without `manifest.json` was interrupted, and is refused, as is a later version of the layout than this release reads. 27.1.0-rc.2 named the format `inbuxa-migrate-files`; that is read as the same format. Run again, it brings the archive up to date with the export: flags that changed, a different active script, a renamed folder. It never deletes. With `--dry-run` it checks the export and counts what it holds, and opens no archive. ### Microsoft Exchange (EWS) ``` inbuxa-migrate import exchange-ews \ [--url ] [--mailbox ] \ [--mailbox-kind primary|archive|public-folders] \ (--auth-basic [--auth-password ] \ | --auth-bearer [TOKEN] [--ews-tenant --ews-client-id \ (--ews-device-code | --ews-client-secret )]) \ [--ews-connections <1..8>] [--ews-getitem-batch ] [--ews-getitem-batch-mib ] \ [--ews-attachment-batch ] \ [--ews-no-syncfolderitems] \ ``` Imports a mailbox from an on-premises Exchange Server through EWS. Without `--url` it uses Autodiscover, and then needs `--mailbox`. It signs in with Basic, with a bearer token acquired beforehand, with OAuth's interactive device-code flow, or with app-only client credentials. Items are fetched in GetItem batches of at most `--ews-getitem-batch` items and `--ews-getitem-batch-mib` MiB (32 by default), `--ews-connections` at a time. The byte cap applies where Exchange reports each item's size, which it does on a full listing; items found through an incremental sync are batched by count. For Exchange Online, use `exchange-graph` instead. Microsoft is retiring EWS in Exchange Online: from October 1, 2026 it is blocked unless a tenant administrator sets `EwsEnabled` to `True` and adds the client id to `EwsAllowedAppIDs`, and on April 1, 2027 it is switched off for every tenant. On-premises Exchange Server is not affected. ### Microsoft Exchange (Graph) ``` inbuxa-migrate import exchange-graph \ (--client-id [--tenant ] [--app-only] | --access-token [TOKEN]) \ [--user ] \ [--mailbox-kind primary|archive] \ [--objects mail,calendar,contacts] \ [--event-body-format text|html] \ [--graph-connections <1..16>] [--top <1..1000>] \ ``` Imports a mailbox from Exchange Online through Microsoft Graph. Without `--access-token` it signs in with the interactive device-code flow. `public-folders` is rejected here: Graph does not expose public folders, so they can only be imported with `exchange-ews`, which for Exchange Online is subject to the retirement described above. With `--app-only` the app signs in as itself, with its client secret, and reads the mailbox `--user` names. No one signs in, so a whole tenant moves with one app, in a [plan](#migrate-many-accounts) with `--user {email}`. - **The app.** Register it in Microsoft Entra, add a client secret, and grant it these Microsoft Graph *application* permissions with admin consent: `User.Read.All`, `Mail.Read`, `MailboxSettings.Read`, `Calendars.Read` and `Contacts.Read`, and `Files.Read.All` for files. To keep it to some mailboxes, scope it with Exchange Online's RBAC for Applications or an application access policy. - **The tenant.** `--tenant` names it, as its id or `name.onmicrosoft.com`; the shared `common` and `organizations` are refused. - **The secret** is read from `$INBUXA_MIGRATE_CLIENT_SECRET`, or asked for. In a plan, the step names it as `clientSecret`. - Its token lasts about an hour and is renewed the same way before it runs out. ## Export ``` inbuxa-migrate export \ --url \ (--auth-basic [--auth-password ] | --auth-bearer [TOKEN]) \ (--account-id | --account-name ) \ [--objects ] [--prune [--yes]] \ ``` Writes `ARCHIVE` into an account on a JMAP server, usually inbuxa. It keeps no state of its own: every run matches the archive against the target afresh. By default it only adds and updates: what the target lacks is created, what it has is brought up to date, and anything on the target that the archive does not cover is left alone. So a second run after a later import carries what changed at the source in between. - **Email** is matched by Message-ID, or without one by sender, subject, date and recipients; where several messages share one, size decides. A message the source kept in several folders -- IMAP and Maildir copies, Gmail labels -- is written once, in all of them. On a match, its keywords (read, flagged and the rest) are set to the archive's, and so are its memberships of folders this run migrated. Folders that exist only on the target are left alone, and a message is never left in no folder. - **Contacts and events** are matched by UID. When both copies carry an `updated` time, the archive's is written only if it is newer; otherwise the properties that differ are written. - **Sieve scripts** are matched by name, and the target's is replaced when its content differs from the archive's. Where the target has a `VacationResponse`, the out-of-office reply is written there, and the script a server keeps for it is not copied as a script. - **Files** are written in the shape the target takes, which `export` asks it once per run: inbuxa takes `nodeType` and `type`. Messages go in batches, as many to an `Email/import` as the target's `maxObjectsInSet` allows, up to 50, with their blobs uploaded several at a time -- the target's `maxConcurrentUpload`, and no more than `--threads`. Each message is still counted on its own: one the target rejects fails alone, and the rest of its batch lands. A batch that ends without a clear answer -- a dropped connection, a gateway timeout -- is never sent again as it was. The target is read first, the messages that arrived are counted as created, and only the rest are imported again, so none is ever doubled. While it runs, export prints a line every few seconds for mail, contacts and events: how many of how many, how fast, and about how long is left. Each type ends with a line of what was created, updated, left unchanged and failed. `--prune` also deletes what is on the target and not in the archive. It asks first; `--yes` answers for it, for scripts. Export speaks JMAP only; for other servers, see [Export to IMAP](#export-to-imap) and [Export to files](#export-to-files). With `--dry-run`, export reads the target and writes nothing to the account. It prints the plan in plain words: for each type, how much would be created, updated, left unchanged or deleted, and what would fail. It catches in advance the failures a real run would hit: - a message larger than the target's `maxSizeUpload`; - a contact, event or other object too large for one request under its `maxSizeRequest`, as happens when a photo is carried inline; - a Sieve script the target would reject. Each script that would be written is checked with `SieveScript/validate`, after any `vnd.stalwart.*` names are renamed, so what is checked is what would be uploaded. The check needs the script as a blob, so the dry run uploads Sieve scripts, and only them; a blob that nothing uses is discarded by the server. A target without `SieveScript/validate` gets one warning, and its scripts are not checked. The plan lists each predicted failure and its reason. When anything would fail, the dry run exits 5, as the real run would, so a script can stop before it starts. ## Export to IMAP ``` inbuxa-migrate export-imap \ --url \ (--auth-basic [--auth-password ] | --auth-bearer [TOKEN] --auth-user ) \ [--allow-cleartext] [--dry-run] \ ``` Writes an archive's mail into an account on any IMAP server, for a target that doesn't speak JMAP. It signs in the way `import imap` does, with the same flags. Contacts, calendars and filters don't go over IMAP; write the filters with `export-managesieve`, and contacts and calendars with `export-carddav` and `export-caldav`. Like `export`, it keeps no state. Each run reads the target folder first, matching messages by Message-ID, or without one by sender, subject, date and recipients, with size deciding between equals. What's missing is appended, with its flags and the time it arrived; what's there gets the archive's flags if they differ. So a second run writes nothing, and an interrupted run is finished by running it again: a message that landed before the connection dropped is found, not doubled. - **Folders.** The inbox goes to INBOX. A sent, drafts, trash, junk or archive folder goes to the one the server marks for it with SPECIAL-USE, such as Gmail's `[Gmail]/Sent Mail`, and is created with that mark when the server allows it. Every other folder is created under the account's personal namespace with its path, using the server's separator; that separator inside a name becomes `_`. Names go as UTF-8 to a server that accepts it, in modified UTF-7 otherwise. - **Flags.** Read, answered, flagged and draft are IMAP's own. Other keywords (Junk, labels) go along where the folder keeps keywords, and the run says how many were left off where it doesn't. Deleted isn't carried, so the next client to expunge removes nothing that was written. - A message the server refuses (too large, over quota) is counted as failed and the run goes on; a dropped connection ends the run. With `--dry-run` it signs in, reads the target with `EXAMINE`, and counts what it would create, append and update, without writing anything. ## Export to ManageSieve ``` inbuxa-migrate export-managesieve \ --url \ (--auth-basic [--auth-password ] | --auth-bearer [TOKEN] --auth-user ) \ [--allow-cleartext] [--dry-run] \ ``` Writes an archive's Sieve scripts into an account on any ManageSieve server (RFC 5804), with the flags `import managesieve` takes. It keeps no state: each run lists the target's scripts, writes each one that is missing or differs with `PUTSCRIPT`, and leaves alone the ones that match, so a second run writes nothing. A script with no name is written as `script-`. - The archive's active script is made active on the target. If no script in the archive is active, the target's active script stays as it is. - A script the server refuses, for instance one using an extension it lacks, is counted as failed with the server's reason, and the run goes on. If the active script is refused, it is not made active. - Scripts are never deleted from the target, and names that match are overwritten only when their content differs. With `--dry-run` it signs in, lists and compares, and checks each script it would write with `CHECKSCRIPT`, so a script the server would refuse is counted as failed before anything is written. A server without `CHECKSCRIPT` (one that advertises no `VERSION`) gets the comparison only. ## Export to CalDAV and CardDAV ``` inbuxa-migrate export-caldav \ --url \ (--auth-basic [--auth-password ] | --auth-bearer [TOKEN]) \ [--allow-cleartext] [--dry-run] \ inbuxa-migrate export-carddav …same flags… ``` Writes an archive's calendars into any CalDAV server, or its address books into any CardDAV server, with the flags `import caldav` and `import carddav` take. `--url` can be the server's root: the account's home is found from the signed-in user's principal, through `/.well-known/caldav` or `/.well-known/carddav` if need be, so a fresh account with nothing in it works. Like the other exports it keeps no state, and a second run writes nothing. - **Collections.** A calendar or address book is matched to the target's by its display name. One that isn't there is made with `MKCALENDAR` or an extended `MKCOL`, with its name, description and (for a calendar) color, at a path made from the name that nothing in the home uses yet. - **Items.** Each event or card goes to `.ics` or `.vcf` in its collection; a UID that isn't a plain name is hashed instead. A new item is written with `If-None-Match: *`. One that is there is read and compared, and written again with `If-Match` on its etag only when it differs. The comparison leaves out what servers rewrite on their own: line folding, the order and case of parameters, `PRODID`, `DTSTAMP` and `REV`. A card's `N` and `ADR` are compared on the parts vCard 3 has, since some servers drop the rest; a change only in those newer parts is not sent. - An item in two collections is written to both. An item, or a collection, the server refuses is counted as failed with the reason, and the run goes on; a collection that can't be made has its items counted as failed too. An item whose server gives no etag isn't overwritten. - Nothing is deleted from the target. With `--dry-run` it signs in, finds the home, reads and compares what is there, and counts what it would create and update, without writing. ## Export to files ``` inbuxa-migrate export-files [--objects ] [--dry-run] ``` Writes `ARCHIVE` out as plain files in open formats, for a server or app that doesn't speak JMAP, or to keep a copy that needs no tool to read. It never opens a network connection. `DIR` must be new or empty, and is made readable by its owner only, like the archive. ``` DIR/ mail/ Maildir++: the inbox here, other folders as .Parent.Child contacts/*.vcf one file per address book calendars/*.ics one file per calendar sieve/*.sieve one file per script files/ the file tree manifest.json what the formats above don't hold ``` - **Mail** is laid out as Dovecot and Courier keep it, so either can serve it as it is. Folder names are in modified UTF-7. A `.` or `/` inside a folder's name becomes `_` on disk, since Maildir++ uses the dot between levels. A message kept in several folders is written to each. Read, answered, flagged, draft, forwarded and deleted are the standard Maildir flags; other keywords (Junk, labels) are the letters `a` to `z`, named in each folder's `dovecot-keywords`, up to 26 per folder. Each file is dated when the message arrived. - **Contacts** are vCard 4.0, and a card in two address books is in both files. **Calendars** are iCalendar, one VCALENDAR each, named by `X-WR-CALNAME`, with each time zone once. Photos and attachments the archive holds go inside as `data:` URIs, as `export` sends them. - **Sieve scripts** are written as they are; the manifest says which is active. - **Files** keep their names and dates. Links are listed in the manifest and never made, since the source chose where they point. Every name comes from the source, so none is used as a path as it stands: separators and names Windows refuses become `_`, and names that clash, even only by case, are numbered. `manifest.json` records the source account, every folder's real name, path, role and message count, each address book and calendar with its file, color and time zone, which Sieve script is active, the identities, and the links. It is written last: a tree without one was interrupted, and the way to finish it is to run again into an empty directory. The layout and the manifest are specified at , so other tools can read and write them too. `import files` reads the whole tree back, manifest and all ([An account export](#an-account-export)); `import maildir` and `import takeout` read the mail, contacts and calendars without it. `--objects` takes the same types as `export`; naming a folder or a message type writes all of mail, and the same for contacts and calendars. With `--dry-run` it counts what it would write and creates nothing. ## Export a directory ``` inbuxa-migrate export-directory \ --url \ (--auth-basic [--auth-password ] | --auth-bearer [TOKEN]) \ [--domain ]... [--dry-run] \ ``` Writes who has an address on a server, so the same accounts can be set up on another one: domains, users, groups, mailing lists, their aliases and quotas, and the tenants and roles they belong to. It reads inbuxa's registry, or Stalwart's, so the login must be an administrator's. Mail and the rest of each account's data move with `import` and the exports above. Nothing secret is written, because nothing secret is asked for: every read names the fields it wants, and credentials, app passwords, OTP seeds, API keys, encryption keys and DKIM keys are not among them. Each new server sets its own passwords and DKIM keys; `import-directory`, below, does that on inbuxa. ``` DIR/ directory.json everything below, exactly, with roles and tenants domains.csv name, enabled, aliases, catch-all, sub-addressing, tenant users.csv address, description, roles, groups, aliases, disk quota groups.csv address, members, aliases, disk quota lists.csv address, recipients, aliases aliases.csv each alias with the address it delivers to ``` - Accounts, groups and lists are named by address, and roles and tenants by name, never by the server's ids. A group lists its members, a user the groups it is in. - Roles are `user`, `admin` or `default`, or the custom roles by name; `permissions` holds what an account adds to its roles (`merge`) or has in their place (`replace`). - Quotas are by name, in bytes or counts (`maxDiskQuota` and the rest); the CSV files show `maxDiskQuota` as `disk_quota`. - In the CSV files, a cell with several values joins them with `;`. The text comes from the server and these files are made to be opened in a spreadsheet, so a cell that one would run as a formula starts with `'`. `directory.json` keeps every value as it is. `--domain` keeps the export to the domains named, with what they use: their tenants and the roles their accounts hold. A group's members on other domains are still listed by address. `DIR` must be new or empty, and is made readable by its owner only. `directory.json` is written last, so a directory without one was interrupted. With `--dry-run` it reads the registry and counts what it would write, and creates nothing. ## Import a directory ``` inbuxa-migrate import-directory \ --url \ (--auth-basic [--auth-password ] | --auth-bearer [TOKEN]) \ --passwords [--domain ]... [--dry-run] \ ``` Sets up on an inbuxa server what `export-directory` wrote: tenants, roles, domains, groups, users and mailing lists, with their aliases, quotas, roles and group memberships. It works through the server's registry, so the login must be an administrator's. Each kind is made before the ones that point at it, so a user finds its domain, its groups and its roles. - **What's already there stays as it is.** A domain, tenant or role with the same name, or an account or list with the same address, is counted as skipped and not changed. So a second run creates nothing, and a run that stopped is finished by running it again. It also means an account made on a run where one of its alias domains was refused keeps no alias there: add that alias by hand. - **Passwords.** Each user it creates gets a generated password: 24 letters and digits, with look-alikes such as `0` and `O` left out. The passwords go into `--passwords FILE` as `email,password` rows, written as each batch of accounts is made. The file must not exist yet and is made readable by its owner only. Hand the passwords out, then delete the file. Accounts that were already there get no password and aren't listed, so each run needs a new file. - **DKIM.** A new domain gets inbuxa's defaults: DKIM keys are made for it, and DNS and certificates are left to you. - Anything the server refuses is counted as failed, with the server's reason, and the rest are still made. An alias or custom role that isn't on the server is left off with a warning. Creates are sent once and not retried, so a lost reply never makes an account twice; run again to pick up what didn't land. `--domain` keeps it to the domains named. With `--dry-run` it reads the server and counts what it would create, sends nothing and writes no file; `--passwords` isn't needed then. ## Migrate many accounts ``` inbuxa-migrate migrate --plan [--parallel ] [--again] [--account ]... [--dry-run] [-q] [--progress json] ``` Moves a list of accounts with one command. The plan file names the steps and the accounts. Each step is one of the commands on this page, written the same way, and `migrate` runs it for every account, several accounts at once. `` is the work directory. It holds an archive and a log per account, the state a later run resumes from, and the report. ```json { "format": "inbuxa-migrate-plan", "formatVersion": 1, "setup": [ {"name": "directory", "args": ["import-directory", "--url", "https://mail.example.org", "--auth-bearer", "--passwords", "passwords.csv", "directory"], "secrets": {"token": "INBUXA_ADMIN_TOKEN"}} ], "accounts": {"directory": "directory/directory.json"}, "steps": [ {"name": "mail", "args": ["import", "imap", "--url", "imaps://old.example.org", "--auth-basic", "{email}*master", "{archive}"], "secrets": {"password": "OLD_MASTER_PASSWORD"}}, {"name": "inbuxa", "args": ["export", "--url", "https://mail.example.org", "--auth-bearer", "--account-name", "{email}", "{archive}"], "secrets": {"token": "INBUXA_ADMIN_TOKEN"}} ] } ``` - **Steps.** `setup` steps run once, before any account: `import-directory` or `export-directory`. The `steps` run for each account, in order, and each has to name `{archive}`. `{email}`, `{local}` and `{domain}` are the account's address and its two halves. Steps run in the plan's directory, so a relative path means the same as it does in the plan. - **Accounts.** A list of addresses, or `{"directory": "…/directory.json"}` for the users that `export-directory` wrote. - **Secrets stay out of the plan.** A step names the environment variable that holds each secret it needs: `password`, `token`, `clientSecret` (EWS, or Graph with `--app-only`) or `graphToken`. A step sees only the secrets it names. A plan that writes a password or token into `args` is refused. A step that needs a secret it doesn't name fails at once instead of waiting for a prompt. - **Signing in for each account.** Each step signs in the way its command does, so the plan decides how. To avoid collecting every user's password, use a login that can act for each account. The example uses Dovecot's master user, `{email}*master`. Use the source's own form where it has one: Exchange impersonation through `--mailbox {email}`, a Graph app with `--app-only --user {email}`, a Google service account with `--google-key key.json --auth-user {email}`, or an administrator on a JMAP source with `--account-name {email}`. - **One account at a time, several at once.** `--parallel` (default 4) sets how many accounts run at the same time. Each step runs as its own process. Its output goes to `//.log`, and one account failing doesn't stop the others. A step that fails stops its account. A step that leaves some objects behind (exit code 5) doesn't. A failed setup step stops the run. - **Resuming.** A second run with the same plan and work directory skips every account that finished. For the rest, it skips the steps that were done and runs everything from the first one that wasn't. `--again` runs every account step once more, done or not. Use it for the final pass once the old server stops taking mail: the steps converge, so it only moves what changed. `--account` limits a run to the accounts named. - **The report.** `/report.csv` has one row per step per account: how it ended (`done`, `partial`, `failed`, `not run`, or `done earlier`), the counts summed over the step's types, and, for one that didn't finish, its last error. Exit code 5 means some account didn't finish. - **Progress for another program.** `--progress json` writes one JSON object per line on stdout, and nothing else there. `event` says which: `start` (`accounts`, `parallel`, `dryRun`), `setup` (a setup step ended), `step` (an account's step began, or ended with `result`, `counts` and `detail`), `account` (an account ended: `email`, `n` of `total`, `result`) and `end` (`done`, `unfinished`, `report`). Messages still go to stderr. The work directory is made readable by its owner only, and so are the logs. With `--dry-run`, each step runs with `--dry-run`, nothing is recorded, and the report goes to `dry-run-report.csv`. An export step reads the archive as it is, so on a first dry run it has nothing to show. ## The guide ``` inbuxa-migrate guide [--port ] [--no-open] ``` Walks through moving a domain, or a few accounts, into inbuxa in the browser. `guide` serves a page on 127.0.0.1 from the binary itself and opens it. The page asks five things in turn: 1. **Where the mail is now:** an IMAP server, a JMAP server (Stalwart or inbuxa), Maildir folders on this machine, Microsoft 365 or Google Workspace. It also asks for a login that can act for every account. On IMAP that's a master user, such as Dovecot's `{email}*master`. On JMAP it's an administrator, with a password or an API key. On Microsoft 365 it's an Entra app with application permissions (`--app-only`), and on Google Workspace a service account's key (`--google-key`). Check signs the app in and says which permissions it lacks, or asks Google for a token for the first account. 2. **Which accounts:** pasted one per line or as a CSV, or read from a JMAP server's account list. The list can be edited before anything runs. 3. **Where to:** the inbuxa server and an administrator's API key, and whether to create the accounts inbuxa doesn't have yet. Each new account gets a generated password, written to a file only its owner can read. 4. **Preview:** a dry run. It signs in for each account, counts what would move, and creates nothing. 5. **Move,** with progress, a report, and a final pass for when the old server stops taking mail. The guide writes an ordinary plan, `/plan.json`, and runs it with `migrate`, so a move started in the browser can be finished from a terminal. The page shows the command. Everything else goes into `` too: the archives, the logs, `work/report.csv`, the passwords file, and the answers so far, in `guide.json`. A guide started again on the same directory picks up where it was. - **Only this browser.** The page is served on 127.0.0.1 alone, at an address with a random token that changes each start. A request without the token, for another host name, or from another site's page is refused. - **Secrets stay in memory.** Passwords and API keys never go into `guide.json` or the plan. The runs get them through environment variables, `MIGRATE_SOURCE_SECRET` and `MIGRATE_INBUXA_TOKEN`, as a plan run from a terminal does. After the guide restarts, the page asks for them again. - `--no-open` prints the address instead of opening a browser. `--port` picks the port; by default any free one is used. ## Plans from answers ``` inbuxa-migrate plan --answers [--source-directory ] ``` Writes what the guide would, for a program that asks the questions itself and runs `migrate`: `/plan.json`, `/preview-plan.json` and, when accounts are to be created, the directory the setup reads. The answers are the guide's, as JSON: `source` (`kind`, `url`, `login`, `path`, `cleartext`, `tenant`, `clientId`, `keyFile`), `accounts`, `create`, and `target` (`url`, `stayOnUrl`, `allowInvalidCerts`). `--source-directory` is what `export-directory` wrote from a JMAP source, so its accounts are set up as they were. The answers hold no secrets, and `plan` refuses them if they do. It says on stdout, as one JSON object, which plans it wrote, where the move's passwords will go, and which variables to set when running them: `MIGRATE_SOURCE_SECRET` for the source's password, API key, client secret or Google key (for Google, a `keyFile` left empty means the key is the secret), and `MIGRATE_INBUXA_TOKEN` for inbuxa's. ## Inspect ``` inbuxa-migrate inspect [TYPE] [--limit ] [--offset ] ``` Read-only dump of a local archive. This command never opens a network connection and never writes to the archive: a path with no archive is an error rather than a new, empty one, and an archive from an older release is shown as it is or refused, never upgraded. While another run holds the archive, it says the archive is in use instead of reading it. - Omit `TYPE` for a per-type summary (counts of every object kind plus blob storage stats). - Pass an object type to dump it: `mailbox`, `email`, `identity`, `sievescript`, `addressbook`, `contactcard`, `calendar`, `calendarevent`, `participantidentity`, `filenode`. - `mailbox` and `filenode` render as a tree (`--limit`/`--offset` are ignored); all other types use a paginated list and respect `--limit` and `--offset`. ## Live tests The tests against real servers -- a Stalwart server as a JMAP source, and Dovecot, Cyrus, Radicale, Baikal and Apache `mod_dav` -- are marked `#[ignore]`. Each test binary boots its own throwaway container through `testcontainers`, pulling the image on first use, so Docker must be running (`docker info` succeeds) before they start. Run them one binary at a time, always with one test thread: ```sh cargo test --test sync_jmap -- --ignored --test-threads=1 # live JMAP import/export/convergence/prune cargo test --test sync_imap -- --ignored --test-threads=1 cargo test --test sync_managesieve -- --ignored --test-threads=1 cargo test --test sync_maildir -- --ignored --test-threads=1 cargo test --test sync_caldav -- --ignored --test-threads=1 cargo test --test sync_carddav -- --ignored --test-threads=1 cargo test --test sync_webdav -- --ignored --test-threads=1 cargo test --test live_stalwart -- --ignored --test-threads=1 cargo test --test seed_smoke -- --ignored --test-threads=1 cargo test --test seed_only -- --ignored --test-threads=1 # Third-party-server tests (one container each): cargo test --test integration_radicale -- --ignored --test-threads=1 cargo test --test integration_baikal -- --ignored --test-threads=1 cargo test --test integration_webdav -- --ignored --test-threads=1 cargo test --test integration_dovecot -- --ignored --test-threads=1 cargo test --test integration_cyrus -- --ignored --test-threads=1 cargo test --test integration_export_imap -- --ignored --test-threads=1 cargo test --test integration_export_managesieve -- --ignored --test-threads=1 cargo test --test integration_export_dav -- --ignored --test-threads=1 # inbuxa itself, an image pinned by digest (run before each release): cargo test --test integration_inbuxa -- --ignored # Slow tests cargo test --test mock_jmap -- --ignored ``` One thread is required, not advised. The tests in a binary share its container, and each one creates and removes the same disposable domain, `inbuxa-migrate.org`, and opens its archive with SQLite's `EXCLUSIVE` lock. Separate binaries each boot their own container on their own ports, so running them one after another is safe. `integration_inbuxa` is the exception: each of its tests starts its own inbuxa server on its own volume, so its tests run in parallel. A test starts the server once in recovery mode to make a domain and an administrator, then again normally, where the administrator makes an API key. It then checks: - a `migrate --plan` run that sets up the accounts with `import-directory` and exports each one with that one key; - a message in two folders arriving once, in both; - a second export carrying over a changed flag; - Sieve scripts getting inbuxa's names. To test another release, change the digest in `tests/integration/inbuxa.rs`.