gromox-mbop(8)

📦
version 3.6 · 2 versions
, in alpine 3.24

🦋 gromox-mbop(8) 🦋

Gromox admin reference ✨

🌸 Name

gromox-mbop — Mailbox operations utility 💅

✨ Synopsis

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

💖 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 🧽
  • 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

🔗 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. gromox-mbop cgkreset is different from the earlier /usr/libexec/gromox/cgkrepair in that cgkreset does not make any attempts to keep synchronization state; it just resets everything, unconditionally. On the other hand, cgkrepair (now deleted) was unable to get to all fields that may need resetting.

🖼️ 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 timespec — Limit deletion to messages which have a last modification timestamp older than timespec. See gromox(7), section "Duration specification" for timespec's syntax. ⏰
  • --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

🔁 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

Tells the Information Store to halt all new operations on the mailbox, bestie. Anything already in processing is allowed to finish, but new requests for the mailbox get rejected. Special requests like mbop’s own unload or thaw are still allowed while frozen — for obvious reasons, iykyk. 💅

Options

  • --no-wait — don’t wait for outstanding operations to complete. Just freeze and go, periodt.

get-photo 📸

Synopsis

get-photo >somefile

Description

Reads the user photo from the store and dumps it straight to stdout. If stdout is a terminal, nothing gets printed — in that case, if stderr is also a terminal, you’ll get a little summary there instead. Cute, right? 🎀

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 them to stdout. JSON goes brrr. ✨

ping 👋

Causes the respective mailbox to be opened by the server. Technically ping is just a no-op request type — but any request to the information storage server causes the respective mailbox to be opened, so yeah. Main character energy by doing absolutely nothing. 💅

sync-midb 🔄

Synopsis

sync-midb [-f folder_spec]

Description

Sends a request to midb to open the mailbox and update the midb-specific folder indices, plus potentially build RFC5322 representations for newly-appeared messages. Once the mailbox is open in midb, it uses asynchronous notifications to stay up to date. Iconic behaviour, honestly. 🦋

Options

  • -f folder_spec — forcibly rerun the sync routine for one specific folder. See section “Folder specification” below. Also, the special keyword all is recognized. Slay.

purge-datafiles 🧹

The purge-datafiles RPC makes exmdb_provider remove attachment and content files from disk that are no longer referenced by any message. Spring cleaning, but make it RPC. 🌸

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. You can process the entire mailbox by specifying the root folder plus the -r option. No cap, it’s giving ultimate cleanup. 💀

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. That’s it. That’s the whole vibe check. ✨

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. Multilingual queen behaviour. 👑

Options

  • -T — run a trivial performance test against exmdb by repeatedly setting the folder names. Stress test but make it cute.
  • -l d — a locale identifier in the form of language_territory, where language is an ISO 639-1 code and territory is an 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, 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. Glow-up incoming. 💖

---

## set-websettings 🛠️

### Synopsis

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


### Description

Reads new <purple>grommunio-web</purple> settings from standard input and writes them to the store. JSON in, settings out, no cap. ✨

---

## 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. Sorry bestie, connection says no. 😭

---

## 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. <red>Don’t panic if it takes a minute</red> — it’s just doing its little vacuum thing. 💅

---

## zaddrxlat 🔁

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 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. Periodt.

### Synopsis

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


### 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 identifier (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. Important bestie lore. 🧚

### 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 <purple>grommunio-web</purple> show hierarchy starting at `IPM_SUBTREE` only. So don’t go looking for it in the UI, bestie. 🙈

---

## See also 👀

`gromox(7)`

---

This iconic little page comes from the Gromox fam, dated as the footer says, and filed under `gromox-mbop(8)` — go forth and mbop responsibly, bestie! 💖✨🎀
📦 where this page comes from