gromox-mbop(8)

Name
gromox-mbop — Mailbox operations utility

Synopsis
gromox-mbop [-d mbox|-u [recipient]@domain.example] command [command-args...]

Summary
gromox-mbop can be used to perform various administrative tasks on mailboxes. Technically, mbop contacts the respective home server(s) and instructs the server to perform the requested action. Unlike tools such as mbck, mkprivate/mkpublic/mkmidb, mbop itself does not do any direct filesystem access on the mailbox.

Global options

-c  Continuous operation mode. If a command in a series (e.g. with foreach.*) fails, do not stop.

-d /var/lib/gromox/user/1/2
    Lookup the mailbox parameters from the associated filesystem location.

-u [user]@example.com
    Lookup the mailbox parameters by the associated username. (To access a public store of a domain, leave out the local part, i.e. use @example.com.)

-v  Verbose mode.

Commands

•   ( command1 c1args ) ( command2 c2args ): command chaining

•   cgkreset: reset synchronization state (PR_CHANGE_KEY, PR_PREDECESSOR_LIST)

•   clear-photo: delete user picture

•   clear-profile: delete user's PHP-MAPI profile

•   clear-rwz: delete IPM.RuleOrganizer FAI messages from the inbox

•   delmsg: issue "delete_message" RPCs for a mailbox

•   echo-maildir: return maildir (for use with foreach.here.*)

•   echo-username: return username (for use with foreach.*)

•   emptyfld: remove objects from folders

•   exaddrxlat: replace all "EX" type addresss in the mailbox's contents

•   foreach.*: iterate over security objects

•   freeze: halt all operations on a mailbox

•   get-freebusy: test FB schedule lookups

•   get-photo: retrieve user image from store and print to stdout

•   get-websettings, get-websettings-persistent, get-websettings-recipients: retrieve settings for grommunio-web

•   ping: cause a mailbox's sqlite files to be opened

•   purge-datafiles: remove orphaned attachments/content files from disk

•   purge-softdelete: remove soft-deleted items from a folder

•   recalc-sizes: recalculate store size

•   set-locale: reset UI language and special folders' names

•   set-photo: read user image from stdin and save to store

•   set-websettings, set-websettings-persistent, set-websettings-recipients: read new grommunio-web settings from stdin and save to store

•   sync-midb: trigger a midb synchronization run

•   thaw: unfreeze a mailbox

•   unload: issue the "unload_store" RPC for a mailbox

•   vacuum: issue the "vacuum" RPC for a mailbox

•   zaddrxlat: replace all "ZARAFA" type addresses in the mailbox's contents

Further documentation

•   SQLite recovery: https://docs.grommunio.com/kb/sqlite.html

Command chaining
( subcommand1 sub1args... )...

It is possible to run multiple mbop commands in sequence for a user. For the option parser to recognize when a command ends and the next one starts, each subcommand invocation shall be wrapped in ( and ). This becomes even more handy in conjunction with the foreach.* pseudocommand.

Subcommands reading data from standard input (e.g. set-photo) cannot be realiably used with chaining, because stdin would be fully consumed the first time around and (...) does not cache the input for any subcommands.

  Examples
Run two commands for a user: gromox-mbop -u a@b.de \( purge-softdelete -r / \) \( purge-datafiles \)

cgkreset
cgkreset resets Change Numbers on all folder and message objects, PR_CHANGE_KEY and PR_PREDECESSOR_LIST values. The use cases for cgkreset are:

•   when the mailbox has CN corruption and Incremental Change Synchronization (by e.g. Outlook or grommunio-sync) is hampered (e.g. message flags/color updates not transferred)

•   when the mailbox has CN corruption and gromox-http/emsmdb has thrown the error "INSERT INTO messages ... UNIQUE constraint failed: messages.change_number"

After execution, .ost files referencing the reset mailbox should be deleted.

clear-photo
The clear-photo command will delete the user picture. Note that, when there is no mailbox-level profile picture set, Gromox server processes may serve an image from another source, e.g. LDAP.

clear-profile
Similar to MSMAPI, PHP-MAPI keeps a MAPI profile which contains a store list and also the settings for grommunio-web. The clear-profile command will delete the copy of this data stored in exmdb. Note that zcore(8) may still hold a copy of the MAPI profile in memory and could write that back to exmdb, nullifying the effect of the clear-profile command. Also, if the store list is absent, a new one will implicitly be created when PHP-MAPI/zcore is used.

clear-rwz
Deletes IPM.RuleOrganizer FAI messages from the inbox.

delmsg

  Synopsis
delmsg -f folder_spec [msgid...]

  Description
This command hard-deletes messages from a store, including issuing proper PR_CHANGE_KEY metadata updates for the sake of Cached Mode clients.

The message IDs taken as arguments on the command-line should be of the GC-value form, i.e. as they appear in the the SQLite database. (For details about GCV, see glossary.rst in the source distribution.)

  Subcommand options

-f folder_spec
    The folder from which to delete the messages. See section "Folder specification" below for syntax details of folder_spec. (If a msgid is specified which is not located in the particular folder, that message will not be deleted.)

--soft
    Perform a soft deletion.

emptyfld

  Synopsis
emptyfld [-MRa] [-t age] [--soft] folder_spec...

  Description
This command deletes objects from one or more folders. emptyfld is normally a one-shot server-side operation. The use of -R,-t is not covered by the existing network protocols, which means that, if either of these options is used, the mbop client program performs the desired recursion and/or timestamp matching locally. This incurs multiple round trips to the server and so takes a bit more time than a "trivial" emptyfld call.

Just to spell it out again explicitly, emptyfld can be in one of three modes:

•   server-assisted operations:

    •   clear contents and/or FAI, no time conditions, no recursion

    •   clear contents and/or FAI, no time conditions, nuke subfolders (recursion barred)

•   client-side traversal:

    •   clear contents and/or FAI, with or without evaluating timestamps, with or without recursion into subfolders, with or without subfolder deletion if empty

  Subcommand options

-M  Exempt normal messages from deletion.

-R  Recurse into subfolders.

-a  Select associated messages (FAI) for deletion.

-t relative-age
    Limit deletion to messages which have a last modification timestamp older than relative-age. See gromox(7), section "Time span syntax" for details. There is currently no option for specifying absolute time.

--delempty
    If, after message deletion, any subfolder is empty, delete it.

--nuke-folders
    Unconditionally delete subfolders outright. For obvious reasons, deleting subfolders disables recursion via -R (because when they are deleted, there is nothing left to recurse into).

--soft
    Switch from hard deletion to soft deletion.

  Soft deletion notes
Soft deletion sets the soft-delete flag (also called "hidden" in Exchange) on messages and/or folders. Soft-deleted objects can be restored/unhidden by the user. Users are technically empowered to perform hard deletions as well, but most mail clients do not offer a user control (e.g. checkbox widget) for it, requiring the use of diagnostic utilities like MFCMAPI or gromox-mbop instead.

When a folder's soft-delete flag changes, the messages and subfolders within are left untouched; their soft-delete flag does not change. In fact, this behaves exactly like setting a directory in the file system to hidden.

  Examples

•   Clear one folder's contents like Outlook/grommunio-web: gromox-mbop -u a@b.de emptyfld --soft DRAFTS

•   Outlook/grommunio-web behave differently when clearing trash! The equivalent mbop command is: gromox-mbop -u a@b.de emptyfld --soft --nuke-folders DELETED

•   Deletion of objects in trash only if untouched for a while: gromox-mbop -u abc@example.com emptyfld -Rt 1week --soft DELETED

exaddrxlat

  Synopsis
exaddrxlat -m file [-r] folder_spec[...]

  Description
Scans messages in the given folders and replaces PR_ADDRTYPE="EX" and related properties by SMTP addresses.

MAPI as a system supports referencing message participants with arbitrary address types, including, but not limited to, SMTP, EX (Exchange/ActiveDirectory DN), FAX numbers, etc.

Contemporary Exchange systems (>= 2010) and/or Outlook versions should be adding secondary metadata when receiving/sending messages such that EX-typed participants become a EX+SMTP hybrid. Really old messages may lack the properties, and GUIs may fail to fill the To: line when replying to old messages. exaddrxlat will replace EX and EX+SMTP hybrids by pure SMTP ones, removing most historic Exchange Directory and ActiveDirectory information.

  Options

-m file
    User map to utilize for translation. See kdb-uidextract(8) for a format description.

-r  Process folders recursively.

foreach.*

  Synopsis
foreach.filter[.filter]* [-j jobs] command [command-args...]

  Description
foreach.* is a pseudoaction for running another subcommands that gromox-mbop offers (e.g. ping, unload, purge-softdelete, etc.) for a number of users. Subcommands reading data from standard input (e.g. set-photo) cannot be realiably used with foreach, because stdin would be fully consumed the first time around and foreach does not cache the input for any subcommands.

  Filters

•   secobj: limit to objects that can be used in ACLs

•   user: regular users

•   dl: distribution lists (groups)

•   sharedmb: shared mailboxes

•   room: room objects

•   equipment: equipment objects

•   contact: GAB contact objects

•   active: active entities

•   susp: entities marked as "suspended"

•   deleted: entities marked as "deleted"

•   mb: entity has a mailbox directory defined

•   here: entity has current host as homeserver (compares `hostname --fqdn` where mbop is run with the SQL.servers.hostname column)

There is no "all" filter. Security objects and Contacts are so vastly different that it just does not make sense to operate on them in the same run.

  Options

-j jobs
    Maximum parallel execution factor. (Experimental.) 0 means autosizing. Only ping/vacuum/unload support this, and the option is otherwise ignored. Use external tools like parallel(1) or make(1) for guaranteed parallelization.
    Default: 1

  Examples

•   Hard-delete all objects which are currently softdeleted: gromox-mbop foreach.mb.here purge-softdelete -r /

get-freebusy

  Synopsis
get-freebusy [-a start_time] [-b end_time] [-x username]

  Description
Runs the get_freebusy routine on the mailbox specified by the global -d/-u option(s) [or the mailbox currently in scope when using foreach.*], and asks for free/busy status within the given time period.

  Options

-a {yyyy-mm-ddThh:mm:ss[Z|+hhmm|-hhmm]|unixtime}
    Limit returned events to occuring on or after this timestamp. Can either be a Unixtime or a ISO 8601 timestamp.

-b {yyyy-mm-ddThh:mm:ss[+hhmm|-hhmm]|unixtime}
    Limit returned events to ocurring before this timestamp.

-x username
    Evaluate access control lists as this identity. If the -x option is omitted, ACL checks are omitted.

freeze

  Synopsis
freeze [--no-wait]

  Description
Tell the Information Store to halt all new operations on the mailbox. Outstanding operations that are currently in processing are allowed to complete. New requests for the mailbox will be rejected. Special requests like (mbop's) unload or thaw are nevertheless allowed in frozen state, for obvious reasons.

  Options

--no-wait
    Do not wait for outstanding operations to complete.

get-photo

  Synopsis
get-photo >somefile

  Description
Reads the user photo from the store and dumps it to stdout. If stdout is a terminal, no output is shown, in which case, if stderr is (also) a terminal, a summary will be shown there.

get-websettings

  Synopsis
get-websettings >file.json
get-websettings-persistent >file.json
get-websettings-recipients >autocomplete.json

  Description
Reads various grommunio-web settings from the store and dumps it to stdout.

ping
Causes the respective mailbox to be opened by the server. (Any request to the information storage server causes the respective mailbox to be opened; and ping is technically just a no-op request type.)

sync-midb

  Synopsis
sync-midb [-f folder_spec]

  Description
Sends a request to midb for opening the mailbox and updating the midb-specific folder indices, as well as potentially building RFC5322 representations for newly-appeared messages. (Once the mailbox is open in midb, it uses asynchronous notifications to stay up to date.)

  Options

-f folder_spec
    Forcibly rerun the sync routine for a single specific folder. See section "Folder specification". In addition, the special keyword "all" is recognized.

purge-datafiles
The "purge-datafiles" RPC makes exmdb_provider remove attachment and content files from disk that are no longer referenced by any message.

purge-softdelete

  Synopsis
purge-softdelete [-r] [-t timespec] folder_spec...

  Description
This command hard-deletes all messages from a folder which are marked as soft-deleted. (The entire mailbox can be processed by specifying the root folder plus the -r option.)

  Subcommand options

-r  Recurse into subfolders.

-t timespec
    Specifies the minimum time to the last modification that soft-deleted messages must have before they are hard-deleted. See gromox(7), section "Duration specification" for timespec's syntax.
    Default: 0 (immediate deletion)

  Examples

•   To process an entire mailbox and wipe everything older than a few days: gromox-mbop -u abc@example.com purge-softdelete -r / -t 10d

recalc-sizes
Recalculates the store size.

set-locale

  Synopsis
set-locale [-Tv] -l id

  Description
First, the set-locale operation changes the "preferred language" setting for the user account. This affects the display of user interfaces like grommunio-web, and also affects the folder language selection when a mailbox is truncated/re-created with gromox-mkprivate(8).

Second, provided Gromox has default folder name translations for the desired locale, set-locale also resets the display names of the mailbox's built-in folders.

  Options

-T  Run a trivial performance test against exmdb by repeatedly setting the folder names.

-l d
    A locale identifier in the form of language_[territory], where language is a ISO 639-1 code and territory is a ISO 3166-1 Alpha 2 code, e.g. ja_JP, pt_BR, pt_PT. This is like the well-known XPG/POSIX locale identifier syntax <https://www.gnu.org/software/libc/manual/html_node/Locale-Names.html>, but no Codeset and no Modifier should be used in Gromox.

-v  Verbose mode. (Same as global -v.)

  Examples

•   gromox-mbop -u abc@example.com set-locale -l ja_JP

set-photo

  Synopsis
set-photo <somefile

  Description
Reads a new user photo from standard input and writes it to the store.

set-websettings

  Synopsis
set-websettings <file.json
set-websettings-persistent <file.json
set-websettings-recipients <autocomplete.json

  Description
Reads new grommunio-web settings from standard input and writes it to the store.

unload
Normally, exmdb_provider(4gx) keeps stores open for up to exmdb_provider.cfg:cache_interval. The "unload_store" RPC to exmdb_provider(4gx) causes the sqlite database (in /var/lib/gromox/.../exmdb/exchange.sqlite3) to be closed. Any subsequent RPC may reopen it, though. The unload RPC is useful after a mailbox was deleted and/or reinitialized with grommunio-admin-api or tools like gromox-mkprivate(8)/gromox-mkpublic(8). [zcore also has store state in memory. This would also need to be purged — but there is no RPC for such action at this time.] unload will fail to succeed if there is still a client connected to the mailbox via a notification channel.

vacuum
Issue the SQLite ".vacuum" command on the user's exchange.sqlite3 file in an attempt to reclaim unused disk space and shrink it. This operation can potentially run for quite some time, during which the mailbox is inaccessible.

zaddrxlat

  Synopsis
zaddrxlat -m file [-r] folder_spec[...]

  Description
Scans messages in the given folders and replaces PR_ADDRTYPE="ZARAFA" and related properties by normal SMTP addresses. See gromox-kdb2mt(8) section "ZARAFA Address Type" for some details. The use case for zaddrxlat is for fixing up addresses after the fact, i.e. when the administrator forgot to employ a user map at the time of running kdb2mt. zaddrxlat does not change ACLs.

  Options

-m file
    User map to utilize for translation. See kdb-uidextract(8) for a format description.

-r  Process folders recursively.

Example

zaddrxlat -m u.map -r "IPM_SUBTREE/Import of blah @2025-12-26"

Folder specification
folder_spec must conform to one of three forms. Either:

•   a numeric identifer (e.g. 13, 0xd)

•   a folder path starting with a slash, optionally followed by a slash-separated sequence of subordinate folder names

•   a folder path starting with a fixed symbolic name, optionally followed by a slash-separated sequence of subordinate folder names

The backslash may be used as a hierarchy separator instead; in any case, the chosen separator must be used consistently in the entire path.

The recognized strings are: CALENDAR, COMMON_VIEWS, CONFLICTS, CONTACTS, DEFERRED_ACTION, DELETED (TRASH, WASTEBASKET), DRAFT, FINDER, INBOX, IPM_SUBTREE, JOURNAL, JUNK, LOCAL_FAILURES, NOTES, OUTBOX, SENT, SERVER_FAILURES, SHORTCUTS, SYNC_ISSUES, TASKS, VIEWS.

The purpose of these names is for referencing a built-in folder irrespective of its assigned name, which is dependent upon translation settings. The symbolic names can be used with private stores only; there are no names defined for public folder contents at this time. There is also no parsing support for slashes in folder names. The slash character is always treated as a hierarchy separator.

  Examples

•   Using the MAPI root: /Top of Information Store/Sent Items/2022

•   Using a symbolic name: IPM_SUBTREE/Sent Items/2022

•   Using a symbolic name: SENT/2022

•   Referencing a folder with a slash can be done by using backslash as the hierarchy separator: SENT\Winter break 2022/2023

The MAPI root is not visible in most clients. MUAs like Outlook and grommunio-web show hierarchy starting at IPM_SUBTREE only.

See also
gromox(7)