shardpostctl(1) – ShardPost docs

SHARDPOSTCTL(1)

ShardPost Manual

SHARDPOSTCTL(1)

NAME

shardpostctl - administrative client for a ShardPost mail server

SYNOPSIS

shardpostctl [connection-flags] command [subcommand] [options] [arguments]

DESCRIPTION

shardpostctl talks to the admin API of a ShardPost server. It connects either to the Unix socket inside the server pod or, with a client certificate, to the mutual-TLS listener. Everything it can do is an operation of that API: there is no direct access to the RADOS store and no way around the roles described below.

An account argument is always the canonical account of the user database. An alias is refused with "not the canonical account" and exit code 64; the only command that accepts one is account show, which reports it as an alias and names the canonical account. Account names are compared in lower case.

Three namespaces exist. An account's own mailboxes have no prefix. Mailboxes shared by another account appear under Shared/<account>/, where the prefix is what server.shared_prefix says (empty: clients see no shared mailboxes at all). Public folders, which belong to no account, live in the reserved namespace ~public and appear to clients under Public/ (server.public_prefix). Pass ~public where a command expects an account to administer them, in quotes: a shell expands an unquoted tilde as a home directory.

In a public folder every flag is shared except \Seen: "read" is a statement about a person, so every account keeps its own, in its own namespace. A command of this tool therefore reads and writes the shared state, which is what a message arrives with and what counts for everyone who has not read it yet; it cannot mark a message read for one person. Public folders have no address of their own: mail reaches them through a Sieve fileinto of an account that has the post right (p), or because somebody with the insert right (i) puts a message there with APPEND, COPY or MOVE. A delivery that names the folder itself (deliver -m) needs the post right as well and fails if the folder is missing or the right is not there — it never falls back to the INBOX.

Commands are grouped by subject. Each group has its own manual page:

shardpostctl-server(1): Version and state of the server itself, and the registrations of the processes that use the store.
shardpostctl-account(1): Look up an account, its quota and the mailboxes shared with it; list the account directory and repair an entry of it; the mark of online quota recounts.
shardpostctl-mailbox(1): List and inspect mailboxes; create, rename and subscribe them; the mark of the mailbox lock of mailbox_delete.
shardpostctl-acl(1): Read, explain and change mailbox permissions.
shardpostctl-message(1): List, search, show, export, flag, copy and move messages.
shardpostctl-sieve(1): Manage Sieve scripts and run a script without side effects.
shardpostctl-job(1): Maintenance jobs, for one account or as a batch over all accounts: plan, apply, watch and cancel.
shardpostctl-learning(1): Inspect and retry jobs of the IMAPSieve learning queue.
shardpostctl-export(1): Export an account to an archive, verify it and restore it.
shardpostctl-deliver(1): Deliver a message like a local delivery agent.
shardpostctl-migrate(1): Copy an account from another IMAP server, keeping its identities.
shardpostctl-trace(1): Switch on a protocol trace for one account.
shardpostctl-auth(1): Flush the auth cache of every server, for one account or for all.
shardpostctl-submission(1): List and cancel the delayed JMAP submissions of an account.
shardpostctl-fts(1): The layouts of the full-text index: the layout 3 mark, the dictionary filter mark, the mark of online runs, the accounts with layout 3, the layout record and the key counts of an account.

CONNECTION FLAGS

These flags come before the command. They select the listener and apply to every command.

-socket path: Unix socket of the admin API. Default: $SHARDPOST_ADMIN_SOCKET, otherwise /run/shardpost/admin.sock. The caller's roles are the ones configured for the socket (admin.socket_roles).
-url https://host:port: Address of the mutual-TLS listener. Overrides -socket. Needs -cert, -key and -ca. The roles are those of the client certificate identity.
-cert file: Client certificate (with -url).
-key file: Private key of the client certificate.
-ca file: CA that signed the server certificate.
-timeout duration: Request timeout, for example 30s, 10m. Default: 2m. For export it does not limit the whole download, only the wait for the response and each pause without data.

ROLES

The admin API authorizes every operation by role. A caller on the Unix socket has the roles listed in admin.socket_roles; a TLS client has the roles of its certificate identity, and optionally an account scope (admin.clients[].accounts).

diagnose: Read-only: server state, accounts, mailboxes, ACLs, quota, job and learning-queue status, delayed submissions. Sees metadata, never message content.
deliver: Local delivery. With deliver:noenforce also over the quota limit.
import: Account import and restore.
trace: Switch the protocol trace of an account.
provision: Create, rename and subscribe mailboxes; change ACLs.
repair: Maintenance jobs that repair; retry learning jobs; repair an account's directory entry; flush the auth cache.
delete: Delete mailboxes and messages, and purge accounts.
content: Read message content: search, headers, export, Sieve script text.
support: Change messages (flags, copy, move) and Sieve scripts; cancel delayed submissions.
export: Export whole accounts.

EXIT STATUS

The exit codes follow sysexits.h:

0: Success.
1: Partly failed; running the command again is safe and is the usual fix (migrate, restore).
64: Usage error: unknown command, missing or invalid argument.
65: The data is wrong: a conflict, a stale version (If-Match), or a damaged archive.
67: No such account, mailbox, message, script or job.
69: The request was rejected or the run failed.
70: The server sent an answer the client did not understand.
73: A file could not be created, or the change would exceed the quota or one of the account limits (errors over_quota and limit_exceeded).
75: Temporary failure. Try again later.
77: The caller lacks the role for this operation.

ENVIRONMENT

SHARDPOST_ADMIN_SOCKET: Default for -socket.
SHARDPOST_ADMIN_URL: Default for -url.
SHARDPOST_ADMIN_CERT: Default for -cert.
SHARDPOST_ADMIN_KEY: Default for -key.
SHARDPOST_ADMIN_CA: Default for -ca.

shardpostctl-migrate(1) reads further SHARDPOST_MIGRATE_* variables; see that page.

OUTPUT

Most commands print a short table for humans. Add --json to get the API answer as JSON instead, which is what scripts should read.

EXAMPLES

In the cluster the client runs in the import sidecar of the server pod, where the socket is:

kubectl -n shardpost exec deploy/shardpost-server -c import -- \


    shardpostctl server status

From outside, against the mutual-TLS listener:

shardpostctl -url https://shardpost.example.org:8443 \


    -cert ops.crt -key ops.key -ca admin-ca.crt \


    account show user@example.org

Is an account healthy, and what does it hold?

shardpostctl account show user@example.org
shardpostctl mailbox list -all user@example.org
shardpostctl check -wait user@example.org

FILES

/run/shardpost/admin.sock: Default admin socket inside the server pod.