gromox-mbop
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.)
Commands
( command1 c1args ) ( command2 c2args ): command chaining
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
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
unload: issue the "unload_store" RPC for a mailbox
vacuum: issue the "vacuum" RPC for a mailbox
Further documentation
SQLite recovery: https://docs.grommunio.com/kb/sqlite.html
Command chaining
�P 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 �P 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 \)
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 server as homeserver
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.mh.ere 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|unixtime}
Left end of the timeframe to query. Unixtime means seconds since the epoch (and is necessarily in UTC), whereas the calendar-based time is read as localtime (so, respecting the TZ environment variable or /etc/localtime).
- -b {yyyy-mm-ddThh:mm:ss|unixtime}
Right end of the timeframe to query.
- -x username
Sets the actor of the operation. This is used for permission checks. If the -x option is omitted, the action is performed as the mailbox owner.
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
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.)
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 [-v] -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
- -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.
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
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.
Folder specification
folder_spec can either be a numeric identifier, or a path-like specification into the folder hierarchy. If the name starts with the slash character '/', it is interpreted as starting from the root; otherwise, the first component must be a special fixed name (untranslated) (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). These special 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 currently in mbop; the slash character is always treated as a hierarchy separator. Examples:
/Top of Information Store/Sent Items/2022
IPM_SUBTREE/Sent Items/2022
SENT/2022
See also
gromox(7)