gromox-mbop.8

.\" SPDX-License-Identifier: CC-BY-SA-4.0 or-later
.\" SPDX-FileCopyrightText: 2022–2024 grommunio GmbH
.TH gromox\-mbop 8 "" "Gromox" "Gromox admin reference"
.SH Name
gromox\-mbop \(em Mailbox operations utility
.SH Synopsis
\fBgromox\-mbop\fP [\fB\-d\fP \fImbox\fP|\fB\-u\fP
[\fIrecipient\fP]\fB@domain.example\fP] \fIcommand\fP [command-args...]
.SH Global options
.TP
\fB\-d\fP \fI/var/lib/gromox/user/1/2\fP
Lookup the mailbox parameters from the associated filesystem location.
.TP
\fB\-u\fP [\fIuser\fP]\fB@example.com\fP
Lookup the mailbox parameters by the associated username. (To access a public
store of a domain, leave out the local part, i.e. use
\fB@\fP\fIexample.com\fP.)
.SH Commands
.IP \(bu 4
clear\-photo: delete user picture
.IP \(bu 4
clear\-profile: delete user's PHP-MAPI profile
.IP \(bu 4
clear\-rwz: delete IPM.RuleOrganizer FAI messages from the inbox
.IP \(bu 4
delmsg: issue "delete_message" RPCs for a mailbox
.IP \(bu 4
echo\-username: return username (diagnostic for use with for\-all\-users)
.IP \(bu 4
emptyfld: remove objects from folders
.IP \(bu 4
for\-all\-users: iterate over all users
.IP \(bu 4
get\-freebusy: test FB schedule lookups
.IP \(bu 4
get\-photo: retrieve user image from store and print to stdout
.IP \(bu 4
get\-websettings, get\-websettings\-persistent, get\-websettings\-recipients:
retrieve settings for grommunio-web
.IP \(bu 4
ping: cause a mailbox's sqlite files to be opened
.IP \(bu 4
purge\-datafiles: remove orphaned attachments/content files from disk
.IP \(bu 4
purge\-softdelete: remove soft-deleted items from a folder
.IP \(bu 4
recalc\-sizes: recalculate store size
.IP \(bu 4
set\-locale: reset UI language and special folders' names
.IP \(bu 4
set\-photo: read user image from stdin and save to store
.IP \(bu 4
set\-websettings, set\-websettings\-persistent, set\-websettings\-recipients:
read new grommunio-web settings from stdin and save to store
.IP \(bu 4
unload: issue the "unload_store" RPC for a mailbox
.IP \(bu 4
vacuum: issue the "vacuum" RPC for a mailbox
.SH Further documentation
.IP \(bu 4
SQLite recovery: https://docs.grommunio.com/kb/sqlite.html
.SH 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.
.SH 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.
.SH clear\-rwz
Deletes IPM.RuleOrganizer FAI messages from the inbox.
.SH delmsg
.SS Synopsis
\fBdelmsg \-f\fP \fIfolder_spec\fP
[\fImsgid\fP...]
.SS Description
This command hard-deletes messages from a store, including issuing proper
PR_CHANGE_KEY metadata updates for the sake of Cached Mode clients.
.PP
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.
.SS Subcommand options
.TP
\fB-f\fP \fIfolder_spec\fP
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.)
.TP
\fB\-\-soft\fP
Perform a soft deletion.
.SH emptyfld
.SS Synopsis
\fBemptyfld\fP [\fB\-MRa\fP] [\fB\-t\fP \fIage\fP] [\fB\-\-soft\fP]
\fIfolder_spec\fP...
.SS 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.
.PP
Just to spell it out again explicitly, emptyfld can be in one of three modes:
.IP \(bu 4
server-assisted operations:
.RS 4
.IP \(bu 4
clear contents and/or FAI, no time conditions, no recursion
.IP \(bu 4
clear contents and/or FAI, no time conditions, nuke subfolders (recursion
barred)
.RE
.IP \(bu 4
client-side traversal:
.RS 4
.IP \(bu 4
clear contents and/or FAI, with or without evaluating timestamps, with or
without recursion into subfolders, with or without subfolder deletion if empty
.RE
.SS Subcommand options
.TP
\fB\-M\fP
Exempt normal messages from deletion.
.TP
\fB\-R\fP
Recurse into subfolders.
.TP
\fB\-a\fP
Select associated messages (FAI) for deletion.
.TP
\fB\-t\fP \fItimespec\fP
Select only messages which have a last modification timestamp older than
\fItimespec\fP. (See further below near purge\-softdelete for a short
explanation of timespec.)
.TP
\fB\-\-delempty\fP
If, after message deletion, any subfolder is empty, delete it.
.TP
\fB\-\-nuke\-folders\fP
Unconditionally delete subfolders outright. For obvious reasons, deleting
subfolders disables recursion via \-R.
.TP
\fB\-\-soft\fP
Perform soft deletion.
.SS 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.
.PP
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.
.SS Examples
.IP \(bu 4
Clear one folder's contents like Outlook/grommunio-web:
gromox\-mbop \-u a@b.de emptyfld \-\-soft DRAFTS
.IP \(bu 4
Outlook/grommunio-web behave differently when clearing trash! The equivalent
mbop command is:
gromox\-mbop \-u a@b.de emptyfld \-\-soft \-\-nuke\-folders DELETED
.IP \(bu 4
Timed deletion of trash:
gromox\-mbop \-u abc@example.com emptyfld \-Rt 1week \-\-soft DELETED
.SH for\-all\-users
.SS Synopsis
\fBfor\-all\-users\fP [\fB\-j\fP \fIjobs\fP] \fIcommand\fP [command-args...]
.SS Options
.TP
\fB\-j\fP \fIjobs\fP
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.
.br
Default: \fI1\fP
.SS Description
Pseudoaction for running one of the other subcommand (e.g. ping, unload.)
.SH get\-freebusy
.SS Synopsis
\fBget\-freebusy\fP [\fB\-a\fP \fIstart_time\fP] [\fB\-b\fP \fIend_time\fP]
[\fB\-x\fP \fIusername\fP]
.SS 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.
.SS Options
.TP
\fB\-a\fP {\fIyyyy-mm-dd\fP\fBT\fP\fIhh:mm:ss\fP|\fIunixtime\fP}
Left end of the timeframe to query.
.TP
\fB\-b\fP {\fIyyyy-mm-dd\fP\fBT\fP\fIhh:mm:ss\fP|\fIunixtime\fP}
Right end of the timeframe to query.
.TP
\fB\-x\fP \fIusername\fP
Perform the action under the given username (for permission tests).
If the \-x option is omitted, the action is performed as the mailbox
owner.
.SH get\-photo
.SS Synopsis
\fBget\-photo >\fP\fIsomefile\fP
.SS 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.
.SH get\-websettings
.SS Synopsis
\fBget\-websettings >\fP\fIfile.json\fP
.br
\fBget\-websettings\-persistent >\fP\fIfile.json\fP
.br
\fBget\-websettings\-recipients >\fP\fIautocomplete.json\fP
.SS Description
Reads various grommunio-web settings from the store and dumps it to stdout.
.SH ping
Any EXRPC causes the respective mailbox to be loaded from the filesystem,
and ping_store is just a practical no-op.
.SH purge\-datafiles
The "purge\-datafiles" RPC makes exmdb_provider remove attachment and content
files from disk that are no longer referenced by any message.
.SH purge\-softdelete
.SS Synopsis
\fBpurge-softdelete\fP [\fB\-r\fP] [\fB\-t\fP \fItimespec\fP]
\fIfolder_spec\fP...
.SS 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.)
.SS Subcommand options
.TP
\fB\-r\fP
Recurse into subfolders.
.TP
\fB\-t\fP \fItimespec\fP
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.
.br
Default: \fI0\fP (immediate deletion)
.SS Examples
.IP \(bu 4
To process an entire mailbox and wipe everything older than a few days:
gromox\-mbop \-u abc@example.com purge\-softdelete \-r / \-t 10d
.SH recalc\-sizes
Recalculates the store size.
.SH set\-locale
.SS Synopsis
\fBset\-locale\fP [\fB\-v\fP] \-l\fP \fIid\fP
.SS 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).
.PP
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.
.SS Options
.TP
\fB\-l\fP \fIid\fP
XPG/POSIX-style locale identifier, e.g. ja_JP, pt_BR.
.TP
\fB\-v\fP
Verbose mode.
.SS Examples
.IP \(bu 4
gromox\-mbop \-u abc@example.com set\-locale \-l ja_JP
.SH set\-photo
.SS Synopsis
\fBset\-photo <\fP\fIsomefile\fP
.SS Description
Reads a new user photo from standard input and writes it to the store.
.SH set\-websettings
.SS Synopsis
\fBset\-websettings <\fP\fIfile.json\fP
.br
\fBset\-websettings\-persistent <\fP\fIfile.json\fP
.br
\fBset\-websettings\-recipients <\fP\fIautocomplete.json\fP
.SS Description
Reads new grommunio-web settings from standard input and writes it to the
store.
.SH 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 \(em 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.
.SH 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.
.SH Folder specification
\fIfolder_spec\fP 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:
.IP \(bu 4
/Top of Information Store/Sent Items/2022
.IP \(bu 4
IPM_SUBTREE/Sent Items/2022
.IP \(bu 4
SENT/2022
.SH See also
\fBgromox\fP(7)