shardpostctl-migrate(1)

The full-text index

Before it copies messages the migrator tells the target how many messages the source's mailboxes hold (STATUS MESSAGES of each); a fresh layout 3 full-text index (see shardpostctl-fts(1)) is sized for them. After every batch it asks the target to check the index: when its objects outgrew fts.shard_target_keys, the target reshards it under the import session, since a fts_layout job would wait for the import to end. The target works up to fts.import_reshard_sync_seconds (60) on the request and then goes on in the background; the migrator asks every five seconds until the reshard ended. Batches sent while it runs are answered 409 and are sent again afterwards. A reshard that fails is a warning; the import goes on and the fts_due worker reshards later. A layout 2 index is never resharded. Run the migrator with shardpostctl -timeout 10m so that the synchronous part of a reshard fits into one request; the default request timeout of two minutes suffices for it, but not for large batches.

Public folders

The second form imports a namespace of the source other than the personal one — a public namespace of Dovecot, as a rule — into the public folders. The account is ~public (quote it: a shell expands the tilde), -source-user is the source account whose view is read, and -source-namespace is the prefix of the namespace there. The folders land below -target-prefix; the namespace's own mailbox, if it has one (Zabbix of the namespace Zabbix/), takes the name of the prefix. The identities are kept exactly as for an account.

What differs from an account:

• Rights are not copied. A public namespace of Dovecot takes its rights from the configuration and from groups, which have no counterpart here. Grant them with shardpostctl-acl(1); an imported folder without an entry is visible to nobody.
• \Seen is private per account. The messages carry the \Seen of the source user, and that is what every account without a state of its own starts from. For each account named with -readers the migrator logs in at the source as that account and records where its \Seen differs, and its subscriptions of these folders. A folder the account does not see at the source is left alone. The source user itself needs no entry for \Seen, only for its subscriptions.
• Pruning stays below the target prefix. Public folders outside it are never removed, the folder the prefix itself names stays, and without a prefix nothing is pruned.
• No Sieve scripts. They belong to accounts.

While such a run is in progress the public namespace is locked: a client gets NO [UNAVAILABLE] for LIST and for every public folder, a session that has a public folder selected is closed within a few seconds, and a delivery that files into a public folder is deferred. The first copy of a large namespace therefore belongs into a quiet hour.

Import into folders nobody uses here yet. A later run makes the target what the source is: a reader's \Seen becomes exactly the source's, so what that account read here in the meantime is unread again, and the reader marks of an earlier run have moved HIGHESTMODSEQ past the source, so a client that synchronized such a folder here between two runs can miss flag changes of the second. Grant the rights after the last run, or keep clients away until then.

Source

-source-addr host:port

Source IMAP server. Required.

-source-tls implicit|starttls|none

How to secure the connection. Default: implicit.

-source-server-name name

Certificate name to expect. Default: the host of -source-addr.

-source-ca file

CA for the source and for ManageSieve. Default: the system roots.

-source-proxy

Send a PROXY v1 header to the source, for load balancers that require it.

-source-timeout duration

Timeout per source command. Default: 2m.

Login

-source-user name

Login name at the source. Default: the account. Required for ~public.

-master-user name

Master user of the source. Without it, the migrator logs in as the user.

-user-format format

How the master login is composed. Default: {user}*{master}.

-password-file file

File holding the password of the (master) user. Required.

Sieve

-sieve-addr host:port

ManageSieve of the source. Without it, Sieve is not copied.

-sieve-tls implicit|starttls|none

Default: starttls.

-sieve-server-name name

Certificate name to expect for ManageSieve.

-sieve-proxy

Send a PROXY v1 header to ManageSieve.

Public folders

-source-namespace prefix

Import this namespace of the source instead of the personal one, for example Mailinglists/. The prefix is the one the source reports in NAMESPACE.

-target-prefix name/

Put this in front of the imported names. Empty, or a mailbox name ending in a slash.

-readers account,...

Accounts whose own \Seen and subscriptions are carried over. Only with the account ~public. Each of them is logged in at the source under its account name, with the same master login; an account that is called something else there cannot be a reader. A folder the account can list but not open is skipped with a warning. A client with a scope needs the readers in it, not only ~public.

Run

-session id

Resume this import session instead of opening a new one.

-no-prune

Keep target mailboxes the source no longer has.

-no-acl

Do not copy mailbox ACLs. A namespace import never copies them.

-reimport

Replace target mailboxes whose UIDVALIDITY no longer matches the source. Their messages are imported again.

-pop3-uidl-format format

The source's pop3_uidl_format (Dovecot syntax), so POP3 clients keep their UIDLs. Without it, POP3 reports the message GUID.

-batch-messages n

Messages per import request. Default: 200.

-batch-bytes n

Bytes per import request; a batch ends at whichever limit comes first, this one or -batch-messages. Default: 33554432 (32 MiB). The server has limits of its own (admin.import.max_batch_bytes, admin.import.max_batch_messages) and refuses a larger batch.

--json

Print the report as JSON.