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 concatenation

  • 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

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 folder and 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.

Subcommand options

-f folder_spec

The folder from which to delete the messages. See below for details. (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 and the mbop client program must perform the desired recursion and/or timestamp matching locally with multiple round trips to the server.

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

Select only messages which have a last modification timestamp older than timespec. (See further below near purge-softdelete for a short explanation of timespec.)

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

--soft

Perform 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

  • Timed deletion of trash: gromox-mbop -u abc@example.com emptyfld -Rt 1week --soft DELETED

foreach.*

Synopsis

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

Description

Iterates over security objects and executes one of the other commands repeatedly. Filter specifications limit the types of security objects.

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

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

Description

Pseudoaction for running one of the other subcommand (e.g. ping, unload.)

Examples

  • Command concatenation: gromox-mbop foreach.mb.here \( purge-softdelete -r / \) \( purge-datafiles \)

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), 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.

-b {yyyy-mm-ddThh:mm:ss|unixtime}

Right end of the timeframe to query.

-x username

Perform the action under the given username (for permission tests). 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

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

Any EXRPC causes the respective mailbox to be loaded from the filesystem, and ping_store is just a practical no-op.

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 mailbox truncate/re-creation 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 id

XPG/POSIX-style locale identifier, e.g. ja_JP, pt_BR.

-v

Verbose mode.

Examples

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.

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)