shardpostctl-acl(1) – ShardPost docs

SHARDPOSTCTL-ACL(1)

ShardPost Manual

SHARDPOSTCTL-ACL(1)

NAME

shardpostctl-acl - read, explain and change mailbox permissions

SYNOPSIS

shardpostctl acl list [--json] account mailbox
shardpostctl acl explain [--json] account mailbox principal
shardpostctl acl set [-mode replace|add|remove] [-if-match etag] account mailbox identifier rights
shardpostctl acl delete [-if-match etag] account mailbox identifier

DESCRIPTION

Permissions follow RFC 4314. The owner of a mailbox always has every right; the owner is therefore never listed as an entry. An identifier is another account of the user database, given in its canonical form, or the literal anyone.

rights is the usual letter string, for example lr (look and read), lrs (and keep the seen flag), lrswipkxte (nearly everything). The letters c and d expand to the newer letters, as in other servers.

acl list

The explicit entries of a mailbox and the ACL generation counter. Role: diagnose.

acl explain

Answers "why does this person see (or not see) this mailbox?" for one principal: the rights that apply, where they come from (an entry for the account itself, an entry for anyone, or nothing), whether the grantee's registry holds the pointer that makes the mailbox appear in the shared namespace (server.shared_prefix), and any findings in plain words. This is the command for share problems, not acl list. Role: diagnose.

acl set

Sets the rights of one identifier. -mode replace (the default) makes the entry exactly rights, add adds those letters to the existing entry and remove takes them away. The server computes and stores the change in one versioned step, so two changes at the same time cannot lose each other. The grantee's pointer follows automatically. Role: provision.

acl delete

Removes the entry of one identifier, which is the same as setting empty rights. Role: provision.

OPTIONS

-mode replace|add|remove: How acl set applies the rights. Default: replace.
-if-match etag: Apply the change only if the ACL is still the version you read. Both acl list and every change print the ETag. On mismatch the command fails with exit code 65 and changes nothing.
--json: Print the answer as JSON.

EXAMPLES

Rights on a public folder: l to see it, r to read, i to add messages with APPEND, p to let a Sieve script file mail into it, e to expunge, a to change its rights.

A public folder has no owner: without an entry, nobody sees it. Let everyone read it and one team write:

shardpostctl acl set '~public' Announcements anyone lr
shardpostctl acl set -mode add '~public' Announcements team@example.org lrswipkxte

Who has rights on a shared mailbox?

shardpostctl acl list user@example.org Shared

A colleague says the shared mailbox does not show up:

shardpostctl acl explain user@example.org Shared colleague@example.org

Give a colleague read access, keeping whatever else is set:

shardpostctl acl set -mode add user@example.org Shared \


    colleague@example.org lr

Take away the right to delete messages, but keep the rest:

shardpostctl acl set -mode remove user@example.org Shared \


    colleague@example.org te

Withdraw a share completely, but only if nobody changed it meanwhile:

shardpostctl acl list user@example.org Shared          # prints the etag
shardpostctl acl delete -if-match '"acl-7"' user@example.org Shared \


    colleague@example.org

After changing ACLs in bulk, let the server check that every grantee's pointer matches its entry; see shardpostctl-job(1):

shardpostctl plan acl_reconcile user@example.org

EXIT STATUS

0: Done.
65: The ACL changed meanwhile (-if-match), or the request conflicts with the current state.
67: No such account or mailbox.
73: The grantee already has as many mailboxes of other accounts shared with it as allowed (limits.shared_pointers in the server configuration; error limit_exceeded). The ACL is unchanged.
75: The grantee is being purged (error account_purging): a grant would outlive it. Try again later; if no purge job runs any more, see shardpostctl account repair.
77: The caller lacks the role, or the identifier is outside its account scope.